From: Thanh Ha Date: Fri, 1 Jun 2018 01:21:11 +0000 (-0400) Subject: Add documentation on intersphinx mapping X-Git-Url: https://gerrit.linuxfoundation.org/infra/gitweb?a=commitdiff_plain;h=1cef20f09b6271876e429498198912d53ee53e89;p=releng%2Fdocs.git Add documentation on intersphinx mapping Provide intersphinx documentation that might not be obvious from the upstream Sphinx documentation. Change-Id: I6d92cf4e03e662ad6880a7f9f61bdc54759dc6f0 Signed-off-by: Thanh Ha --- diff --git a/docs/_static/objects.inv.example b/docs/_static/objects.inv.example new file mode 100644 index 0000000..32bc98f --- /dev/null +++ b/docs/_static/objects.inv.example @@ -0,0 +1,51 @@ +std:doc + ansible Ansible Guide : ansible.html + best-practices Best Practices : best-practices.html + gerrit Gerrit Guide : gerrit.html + gpg GPG2 (GnuGP 2) Guide : gpg.html + helpdesk LF Helpdesk : helpdesk.html + index Linux Foundation Releng Documentation : index.html + infra/index Infrastructure Guide : infra/index.html + infra/inventory Inventory : infra/inventory.html + infra/jenkins Jenkins : infra/jenkins.html + infra/nexus Nexus : infra/nexus.html + infra/openstack OpenStack Management : infra/openstack.html + jenkins Jenkins Guide : jenkins.html + nexus2 Nexus 2 Guide : nexus2.html + project-bootstrap New Project Bootstrap : project-bootstrap.html + project-documentation Project Documentation Guide : project-documentation.html +std:label + dco Developer’s Certificate of Origin : gerrit.html#dco + genindex Index : genindex.html + gerrit-push-git-push Push using git push : gerrit.html#gerrit-push-git-push + gerrit-push-git-review Push using git review : gerrit.html#gerrit-push-git-review + gerrit-push-output Push output : gerrit.html#gerrit-push-output + gerrit-topics Gerrit Topics : gerrit.html#gerrit-topics + get-sandbox-access Get access to the Jenkins Sandbox : jenkins.html#get-sandbox-access + jenkins-guide Jenkins Guide : jenkins.html#jenkins-guide + jenkins-infra Jenkins : infra/jenkins.html#jenkins-infra + jenkins-sandbox-push-jobs Push jobs to Jenkins Sandbox : jenkins.html#jenkins-sandbox-push-jobs + jjb-push-cli Push jobs via JJB CLI : jenkins.html#jjb-push-cli + jjb-push-gerrit-comment Push jobs via Gerrit comment : jenkins.html#jjb-push-gerrit-comment + lfdocs-create-rtd Add a project to ReadTheDocs : project-documentation.html#lfdocs-create-rtd + lfdocs-global-jjb-templates Global JJB Templates : jenkins.html#lfdocs-global-jjb-templates + lfdocs-helpdesk LF Helpdesk : helpdesk.html#lfdocs-helpdesk + lfdocs-jenkins-sandbox Jenkins Sandbox : jenkins.html#lfdocs-jenkins-sandbox + lfdocs-packer-images Packer Images : jenkins.html#lfdocs-packer-images + lfdocs-proj-docs Project Documentation Guide : project-documentation.html#lfdocs-proj-docs + lfreleng-docs Linux Foundation Releng Documentation : index.html#lfreleng-docs + lfreleng-docs-ansible Ansible Guide : ansible.html#lfreleng-docs-ansible + lfreleng-docs-best-practices Best Practices : best-practices.html#lfreleng-docs-best-practices + lfreleng-docs-bootstrap New Project Bootstrap : project-bootstrap.html#lfreleng-docs-bootstrap + lfreleng-docs-gerrit Gerrit Guide : gerrit.html#lfreleng-docs-gerrit + lfreleng-docs-gpg GPG2 (GnuGP 2) Guide : gpg.html#lfreleng-docs-gpg + lfreleng-infra Infrastructure Guide : infra/index.html#lfreleng-infra + lfreleng-infra-inventory Inventory : infra/inventory.html#lfreleng-infra-inventory + lfreleng-infra-nexus Nexus : infra/nexus.html#lfreleng-infra-nexus + lfreleng-infra-openstack OpenStack Management : infra/openstack.html#lfreleng-infra-openstack + modindex Module Index : py-modindex.html + nexus2-guide Nexus 2 Guide : nexus2.html#nexus2-guide + push-job Push a Job : jenkins.html#push-job + register-key-gerrit Register your SSH key with Gerrit : gerrit.html#register-key-gerrit + search Search Page : search.html + verify-jjb Verify JJB : jenkins.html#verify-jjb diff --git a/docs/project-documentation.rst b/docs/project-documentation.rst index 92105b9..63ccc18 100644 --- a/docs/project-documentation.rst +++ b/docs/project-documentation.rst @@ -152,3 +152,120 @@ ReadTheDocs know where to pull your docs to build from. Typically the repo name. Forward slashes are not allowed so convert them to hyphens. + +Appendix +======== + +Intersphinx Linking +------------------- + +This is supplemental documentation for upstream Sphinx docs on intersphinx_ +linking and Sphinx linking in general. Please refer to the upstream docs here: + +* intersphinx_ +* linking_ + +When working with related projects that generate separate Sphinx documentation +that need to be cross referenced, intersphinx_ linking_ is the recommended way +to link them. + +As a refresher, refer to the Sphinx documentation on linking_ and review the +upstream docs for the ``:doc:`` and ``:ref:`` link types. ``:any:`` is a useful +helper function to let Sphinx guess if a link is a ``:doc:`` or a ``:ref:`` link. + +In most cases folks use these link references to link to local documentation, +we can use these for intersphinx_ linking_ to another project's +public docs as well via a ``namespace`` and configuration in ``conf.py``. + +The configuration is a dictionary containing a ``key`` which we will refer to +as a doc ``namespace`` and a tuple with a link to the project's public +documentation. This ``namespace`` is locally significant and is a free form +word so set it to anything, then within the local project use it to reference +an external doc. + +:Example: + + .. code-block:: python + + intersphinx_mapping = { + 'python': ('https://docs.python.org/3', None), + } + +conf.py configuration +^^^^^^^^^^^^^^^^^^^^^ + +The ``lfdocs-conf`` project already provides common +`LF docs related intersphinx links +`_ +for projects using ``lfdocs-conf``. + +To add to the intersphinx link dictionary define ``intersphinx_mapping`` +in the local ``conf.py`` file, refer to the example above. This overrides the +``intersphinx_mapping`` variable. If using ``lfdocs-conf``, we recommend +appending to the list instead by setting the following: + +.. code-block:: python + + intersphinx_mapping['key'] = ('https://example.org/url/to/link', None) + intersphinx_mapping['netvirt'] = ('http://docs.opendaylight.org/projects/netvirt/en/latest/', None) + +Since lfdocs-conf defines the intersphinx_mapping dictionary, the code +above will append to it using a key-value pair. More examples of intersphinx +mapping exist in the `OpenDaylight conf.py +`_. + +Cross-Reference external docs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Using the ``namespace`` we can refer to ``docs`` and ``labels`` in external +project documentation in the same way we can refer to local documentation. + +:Example: + + .. code-block:: ReST + + * :doc:`Global JJB ` + * :ref:`CI Jobs ` + +:Demo: + + * :doc:`Global JJB ` + * :ref:`CI Jobs ` + +From the example, we insert the global-jjb docs namespace as deliminated by the +colon ``:`` symbol inside of link reference to point Sphinx to the global-jjb +project docs link. + +.. tip:: + + The above example highlights a bad practice in some LF Docs projects where + we were namespacing label definitions using code such as + ``.. _lf-global-jjb-jenkins-cfg-merge``. This is redundant and unnecessary + as the project is already namespaced by the ``intersphinx_mapping`` + configuration. When defining labels, define them with locally significant + names and use ``intersphinx_mapping`` to handle the namespace. + +Inspect the objects.inv for links +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Every Sphinx build produces an objects.inv. In a local build this file is +where the html output is for example ``docs/_build/html/objects.inv``, +online the file is at the html root +``https://docs.releng.linuxfoundation.org/en/latest/objects.inv``. We can +use this file to inspect the types of reference links we can use for a project. + +.. code-block:: bash + :caption: Inspecting objects.inv with Sphinx + + # In a virtualenv + pip install sphinx + python -m sphinx.ext.intersphinx path/to/objects.inv + +Links listed as ``std:doc`` refer to the ``:doc:`` syntax while +links listed as ``std:label`` refer to the ``:ref:`` syntax. + +.. literalinclude:: _static/objects.inv.example + :caption: Example lf-docs objects.inv + +.. _intersphinx: http://www.sphinx-doc.org/en/master/ext/intersphinx.html +.. _linking: http://www.sphinx-doc.org/en/stable/markup/inline.html