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 <thanh.ha@linuxfoundation.org>

diff --git a/docs/_static/objects.inv.example b/docs/_static/objects.inv.example
new file mode 100644 (file)
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 (file)
--- 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
+<https://github.com/lfit/releng-docs-conf/blob/master/docs_conf/conf.py>`_
+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
+<https://github.com/opendaylight/docs/blob/master/docs/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 <global-jjb:index>`
+       * :ref:`CI Jobs <global-jjb:lf-global-jjb-jenkins-cfg-merge>`
+
+:Demo:
+
+    * :doc:`Global JJB <global-jjb:index>`
+    * :ref:`CI Jobs <global-jjb:lf-global-jjb-jenkins-cfg-merge>`
+
+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