From 0bea92dd2c88d3286b9a805a0420b0ee9ad90156 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 8 Jul 2021 22:03:33 +0200 Subject: [PATCH 1/6] Fix leftover terminology inconsistencies --- doc/tutorial/index.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 6ff26869516..122d3861f64 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,8 +437,8 @@ 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 From 06824e290b3e1bc2c321afdcc65adc8e14a47264 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 8 Jul 2021 22:03:59 +0200 Subject: [PATCH 2/6] Add section on intersphinx --- doc/tutorial/index.rst | 61 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 122d3861f64..3c3da119cbe 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -444,6 +444,67 @@ cross-reference to. If you do not include an explicit title, hence using ``Installation``). Both the ``:doc:`` and the ``:ref:`` roles will be rendered as hyperlinks in the HTML documentation. +Referencing external projects with intersphinx +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Most likely you are 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 objects from 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' -A5 + 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 + +You can now introduce a cross-reference to the ``contents`` section of the +Sphinx documentation as follows, prefixing it by `sphinx:` to better identify +it is an external one: + +.. code-block:: rst + :caption: docs/source/index.rst + + .. note:: + + This documentation is built on Sphinx, + :doc:`find out more in their docs `. + +And finally, to actually link our documentation with the Sphinx one, add a +:confval:`intersphinx_mapping` dictionary to your as follows: + +.. code-block:: python + :caption: docs/source/conf.py + + intersphinx_mapping = { + 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), + } + +After you build the HTML documentation with ``make html``, you will see a link +pointing to that specific section of the Sphinx documentation! + Where to go from here --------------------- From 9dade12faa75780957e7644138e3a8a72ea95361 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 8 Jul 2021 22:41:45 +0200 Subject: [PATCH 3/6] Style improvements Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> --- doc/tutorial/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 3c3da119cbe..fd42da08052 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -447,10 +447,10 @@ as hyperlinks in the HTML documentation. Referencing external projects with intersphinx ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Most likely you are depending on some open source libraries for your own +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 objects from other +Sphinx is the ability to generate cross-references to other projects available online, using the :doc:`intersphinx ` extension. @@ -482,7 +482,7 @@ Sphinx itself: You can now introduce a cross-reference to the ``contents`` section of the Sphinx documentation as follows, prefixing it by `sphinx:` to better identify -it is an external one: +it as an external reference: .. code-block:: rst :caption: docs/source/index.rst @@ -503,7 +503,7 @@ And finally, to actually link our documentation with the Sphinx one, add a } After you build the HTML documentation with ``make html``, you will see a link -pointing to that specific section of the Sphinx documentation! +pointing to that specific page of the Sphinx documentation! Where to go from here --------------------- From 8511726a3c03e6f61443ad7f8df0e19e0749aa39 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 8 Jul 2021 22:47:23 +0200 Subject: [PATCH 4/6] Make `grep` command more explicit --- doc/tutorial/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index fd42da08052..35bfff692e4 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -472,7 +472,7 @@ 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' -A5 + (.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 From 89aa4f965cd950272c8edbee6457c6c1bc9424cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 8 Jul 2021 22:52:53 +0200 Subject: [PATCH 5/6] Reorder intersphinx steps to make them more natural --- doc/tutorial/index.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 35bfff692e4..9a9dfe50c0a 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -480,9 +480,19 @@ Sphinx itself: 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, prefixing it by `sphinx:` to better identify -it as an external reference: +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 @@ -492,16 +502,6 @@ it as an external reference: This documentation is built on Sphinx, :doc:`find out more in their docs `. -And finally, to actually link our documentation with the Sphinx one, add a -:confval:`intersphinx_mapping` dictionary to your as follows: - -.. code-block:: python - :caption: docs/source/conf.py - - intersphinx_mapping = { - 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), - } - After you build the HTML documentation with ``make html``, you will see a link pointing to that specific page of the Sphinx documentation! From 87c36503672256c5b1f85e63a772c30ece56c0c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Fri, 9 Jul 2021 15:10:48 +0200 Subject: [PATCH 6/6] Style improvement Co-authored-by: Jakob Lykke Andersen --- doc/tutorial/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 9a9dfe50c0a..3ca1248c38b 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -449,7 +449,7 @@ 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 +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.