diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 6ff26869516..3ca1248c38b 100644 --- a/doc/tutorial/index.rst +++ b/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 ` 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 -```` 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 +```` 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 powerful features of +Sphinx is the ability to generate cross-references to other +projects available online, using the +:doc:`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 `. + +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 ---------------------