New Sphinx tutorial (intersphinx, postponed)

doc/tutorial/index.rst

@@ -267,7 +267,7 @@ follows:
        'sphinx.ext.duration',
    ]
 
-After that, every time you generate your documentation, you will see a short
+After that, every time you build your documentation, you will see a short
 durations report at the end of the console output, like this one:
 
 .. code-block:: console
@@ -437,13 +437,74 @@ And make the sentence you added in ``index.rst`` look like this:
    :ref:`install <installation>` the project.
 
 Notice a trick here: the ``install`` part specifies how the link will look like
-(we want it to be a specific word, so the sentence makes sense), whereas the
-``<installation>`` part refers to the actual label we want to add a
+(in this case, using a specific word so the sentence makes sense), whereas the
+``<installation>`` part refers to the actual label you want to add a
 cross-reference to. If you do not include an explicit title, hence using
 ``:ref:`installation```, the section title will be used (in this case,
 ``Installation``). Both the ``:doc:`` and the ``:ref:`` roles will be rendered
 as hyperlinks in the HTML documentation.
 
+Referencing external projects with intersphinx
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You are likely depending on some open source libraries for your own
+project, and there is a chance those dependencies have their documentation
+written in Sphinx and available online. One of the most powerful features of
+Sphinx is the ability to generate cross-references to other
+projects available online, using the
+:doc:`intersphinx </usage/extensions/intersphinx>` extension.
+
+To enable it, first add ``sphinx.ext.intersphinx`` to the list of extensions:
+
+.. code-block:: python
+   :caption: docs/source/conf.py
+
+   extensions = [
+       'sphinx.ext.duration',
+       'sphinx.ext.intersphinx',
+   ]
+
+The way to know whether you can reference an external project is to check
+if it has a publicly available ``objects.inv``, which can be parsed calling
+``python -m sphinx.ext.intersphinx``. For example, this is the output for
+Sphinx itself:
+
+.. code-block:: console
+   :emphasize-lines: 4
+
+   (.venv) $ python -msphinx.ext.intersphinx https://www.sphinx-doc.org/en/master/objects.inv  | grep 'std:doc' --after-context 5
+   std:doc
+           changes                                  Changelog                               : changes.html
+           contents                                 Sphinx documentation contents           : contents.html
+           development/builders                     Configuring builders                    : development/builders.html
+           development/index                        Extending Sphinx                        : development/index.html
+           development/overview                     Developing extensions overview          : development/overview.html
+
+To link your documentation with the Sphinx one, add a
+:confval:`intersphinx_mapping` dictionary to your ``conf.py`` as follows:
+
+.. code-block:: python
+   :caption: docs/source/conf.py
+
+   intersphinx_mapping = {
+       'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+   }
+
+You can now introduce a cross-reference to the ``contents`` section of the
+Sphinx documentation as follows, optionally prefixing it by ``sphinx:``, the
+key you used in the ``intersphinx_mapping`` configuration:
+
+.. code-block:: rst
+   :caption: docs/source/index.rst
+
+   .. note::
+
+      This documentation is built on Sphinx,
+      :doc:`find out more in their docs <sphinx:contents>`.
+
+After you build the HTML documentation with ``make html``, you will see a link
+pointing to that specific page of the Sphinx documentation!
+
 Where to go from here
 ---------------------