From 1cbaf7ff302810127b4803e79a7991037aa34802 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Tue, 15 Jun 2021 17:55:09 +0200 Subject: [PATCH 01/30] Minor style fixes --- doc/tutorial/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 993a308d3a8..402efbac767 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -134,7 +134,7 @@ the documentation as HTML for the first time. To do that, run this command: (.venv) $ sphinx-build -b html docs/source/ docs/build/html -And finally, open `docs/build/html/index.html` in your browser. You should see +And finally, open ``docs/build/html/index.html`` in your browser. You should see something like this: .. image:: /_static/tutorial/lumache-first-light.png @@ -145,7 +145,7 @@ Making some tweaks to the index ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``index.rst`` file that ``sphinx-quickstart`` created has some content -already, and it gets rendered as the front page of our HTML documentation. It +already, and it gets rendered as the front page of your HTML documentation. It is written in reStructuredText, a powerful markup language. Modify the file as follows: From 167828fde9f0a2fbea687acf08ccf397214ae6c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Tue, 15 Jun 2021 17:55:53 +0200 Subject: [PATCH 02/30] Add section about exporting to other formats --- doc/tutorial/index.rst | 52 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 50 insertions(+), 2 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 402efbac767..996ac54cce2 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -141,8 +141,11 @@ something like this: There we go! You created your first HTML documentation using Sphinx. -Making some tweaks to the index -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +First steps to document your project using Sphinx +------------------------------------------------- + +Converting your documentation to HTML +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``index.rst`` file that ``sphinx-quickstart`` created has some content already, and it gets rendered as the front page of your HTML documentation. It @@ -184,6 +187,51 @@ as before, or leverage the convenience script as follows: After running this command, you will see that ``index.html`` reflects the new changes! +Exporting your documentation to other formats +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sphinx supports a variety of formats apart from HTML, including PDF, EPUB, +:ref:`and more `. For example, to build your documentation as an +e-book in EPUB format, run this command from the ``docs`` directory: + +.. code-block:: console + + (.venv) $ make epub + +After that, you will see the files corresponding to the e-book under +``docs/build/html/``. You can either open ``Lumache.epub`` with an +EPUB-compatible e-book viewer, like `Calibre `_, +or preview ``index.xhtml`` on a web browser. + +.. note:: + + To quickly display a complete list of possible output formats, plus some + extra useful commands, you can run :code:`make help`. + +Each output format has some specific configuration options that you can tune, +:ref:`including EPUB `. For instance, the default value of +:confval:`epub_show_urls` is ``inline``, which means that, by default, URLs are +shown right after the corresponding link, in parentheses. You can change that +behavior by adding the following code at the end of your ``conf.py``: + +.. code-block:: python + + # EPUB options + epub_show_urls = 'footnote' + +With this configuration value, and after running ``make epub`` again, you will +notice that URLs appear now as footnotes, which avoids cluttering the text. +Sweet! + +.. warning:: + + Generating a PDF using Sphinx can be done running ``make latexpdf``, + provided that the system has a working :math:`\LaTeX` installation, + as explained in the documentation of :class:`sphinx.builders.latex.LaTeXBuilder`. + Although this is perfectly feasible, such installations are often big, + and in general LaTeX requires careful configuration in some cases, + so PDF generation is out of scope for this tutorial. + Where to go from here --------------------- From dc5dc61e3fe828ae1b5dafa89f060f1c5a931226 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Wed, 16 Jun 2021 16:17:38 +0200 Subject: [PATCH 03/30] Turn plain image into figure --- doc/tutorial/index.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 996ac54cce2..b12e84fc183 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -137,7 +137,12 @@ the documentation as HTML for the first time. To do that, run this command: And finally, open ``docs/build/html/index.html`` in your browser. You should see something like this: -.. image:: /_static/tutorial/lumache-first-light.png +.. figure:: /_static/tutorial/lumache-first-light.png + :width: 80% + :align: center + :alt: Freshly created documentation of Lumache + + Freshly created documentation of Lumache There we go! You created your first HTML documentation using Sphinx. From 1e492189935f68653c3e7311535bd3cfb7ef6c24 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Wed, 16 Jun 2021 16:19:32 +0200 Subject: [PATCH 04/30] Add tutorial section about extensions and themes --- doc/_static/tutorial/lumache-furo.png | Bin 0 -> 51223 bytes doc/tutorial/index.rst | 71 ++++++++++++++++++++++++++ doc/usage/extensions/index.rst | 4 ++ 3 files changed, 75 insertions(+) create mode 100644 doc/_static/tutorial/lumache-furo.png diff --git a/doc/_static/tutorial/lumache-furo.png b/doc/_static/tutorial/lumache-furo.png new file mode 100644 index 0000000000000000000000000000000000000000..c7aaee796cb5561c1f853bc0d68e63a2fb0044a6 GIT binary patch literal 51223 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 YwevRYog7{`;BN^T2}SV|(a+!i2i_fLX8-^I literal 0 HcmV?d00001 diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index b12e84fc183..3b078409d41 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -237,6 +237,77 @@ Sweet! and in general LaTeX requires careful configuration in some cases, so PDF generation is out of scope for this tutorial. +More Sphinx customization using extensions +------------------------------------------ + +Enabling a built-in extension +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In addition to these configuration values, you can customize Sphinx even more +by using :doc:`extensions <../usage/extensions/index>`. Sphinx ships several +:ref:`built-in ones `, and there are many more +:ref:`maintained by the community `. + +For example, to enable the :mod:`sphinx.ext.duration` extension, +locate the ``extensions`` list in your ``conf.py`` and add one element as +follows: + +.. code-block:: python + + # Add any Sphinx extension module names here, as strings. They can be + # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom + # ones. + extensions = [ + 'sphinx.ext.duration', + ] + +After that, every time you generate your documentation, you will see a short +durations report at the end of the console output, like this one: + +.. code-block:: console + + (.venv) $ make html + ... + The HTML pages are in build/html. + + ====================== slowest reading durations ======================= + 0.042 temp/source/index + +Using a third-party theme +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Themes, on the other hand, are a particular class of extensions that allow you +to customize the appearance of your documentation. Again, Sphinx has several +:ref:`built-in themes `, and there are also third-party ones. + +For example, to use the `Furo `_ third-party theme +in your HTML documentation, first you will need to install it with ``pip`` on +your Python virtual environment, like this: + +.. code-block:: console + + (.venv) $ pip install furo + +And then, locate the ``html_theme`` variable on your ``conf.py`` and replace +its value as follows: + +.. code-block:: python + + # The theme to use for HTML and HTML Help pages. See the documentation for + # a list of builtin themes. + # + html_theme = 'alabaster' + +With this change, you will notice that your HTML documentation has now a new +appearance: + +.. figure:: /_static/tutorial/lumache-furo.png + :width: 80% + :align: center + :alt: HTML documentation of Lumache with the Furo theme + + HTML documentation of Lumache with the Furo theme + Where to go from here --------------------- diff --git a/doc/usage/extensions/index.rst b/doc/usage/extensions/index.rst index 0d446cb61a3..389d9ccbd9e 100644 --- a/doc/usage/extensions/index.rst +++ b/doc/usage/extensions/index.rst @@ -10,6 +10,8 @@ This chapter describes the extensions bundled with Sphinx. For the API documentation on writing your own extension, refer to :ref:`dev-extensions`. +.. _built-in-extensions: + Built-in extensions ------------------- @@ -38,6 +40,8 @@ These extensions are built in and can be activated by respective entries in the viewcode +.. _third-party-extensions: + Third-party extensions ---------------------- From 2058acc4f9c040a7753b3a266a575af601315f60 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Wed, 16 Jun 2021 20:57:09 +0200 Subject: [PATCH 05/30] Add local table of contents --- doc/tutorial/index.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 3b078409d41..2502bb4700f 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -27,6 +27,9 @@ a basic understanding of how it works, as well as a working Python installation for development, since you will use *Python virtual environments* to create the project. +.. contents:: Contents + :local: + Getting started --------------- From 57b0a1b4657c4612be91c61e9bca0f8fa8875d58 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Wed, 16 Jun 2021 23:50:17 +0200 Subject: [PATCH 06/30] Add section about the toctree --- doc/tutorial/index.rst | 71 +++++++++++++++++++++++++++ doc/usage/restructuredtext/basics.rst | 2 + 2 files changed, 73 insertions(+) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 2502bb4700f..bd0731b8782 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -311,6 +311,77 @@ appearance: HTML documentation of Lumache with the Furo theme +Narrative documentation in Sphinx +--------------------------------- + +Inserting documents in the project hierarchy +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As discussed at the beginning, ``index.rst`` is the :term:`master document`, +whose main function is to serve as a welcome page and to contain the root of +the "table of contents tree" (or *toctree*). Sphinx allows you to assemble +a project from different files, which is helpful when the project grows. + +As an example, create a new file ``docs/source/usage.rst`` (next to +``index.rst``) with these contents: + +.. code-block:: rest + + Usage + ===== + + Installation + ------------ + + To use Lumache, first install it using pip: + + .. code-block:: console + + (.venv) $ pip install lumache + +This new file contains two :ref:`section ` headers, normal +paragraph text, and a ``code-block`` directive that renders a block of content +as source code, with appropriate syntax highlighting (in this case, generic +``console`` text). + +.. note:: + + You can read `the list of available highlight + languages `_ in the Pygments + documentation. + +The structure of the document is determined by the succession of heading +styles, which means that, by using ``---`` for the "Installation" section +after ``===`` for the "Usage" section, you have declared "Installation" to +be a *subsection* of "Usage". + +In addition, add a ``toctree`` :ref:`directive ` at the end +of ``index.rst`` including the document you just created, +as follows: + +.. code-block:: rest + + Contents + -------- + + .. toctree:: + + usage + +This step inserts that document in the root of the *toctree*, so now it belongs +to the structure of your project. If you export the documentation to HTML +running ``make html``, you will see that the ``toctree`` gets rendered as a +list of hyperlinks, and this allows you to navigate to the new page you +just created. Neat! + +.. warning:: + + Every document should belong to a *toctree*. Otherwise, Sphinx will emit a + ``WARNING: document isn't included in any toctree``, and the end result + will depend on the builder. For the HTML builder, the page will not be + linked from anywhere (therefore it will not be discoverable), whereas for + the PDF builder, it will not be included at all. + Where to go from here --------------------- diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst index 1c601ea2e01..d96b1fe3867 100644 --- a/doc/usage/restructuredtext/basics.rst +++ b/doc/usage/restructuredtext/basics.rst @@ -224,6 +224,8 @@ Internal linking is done via a special reST role provided by Sphinx, see the section on specific markup, :ref:`ref-role`. +.. _rst-sections: + Sections -------- From e022872f3ba5e59c965e7b9b89c9479c807426b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 17 Jun 2021 00:37:32 +0200 Subject: [PATCH 07/30] Add section about cross-references --- doc/tutorial/index.rst | 50 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index bd0731b8782..c4de85cc52b 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -382,6 +382,56 @@ just created. Neat! linked from anywhere (therefore it will not be discoverable), whereas for the PDF builder, it will not be included at all. +Adding cross-references +~~~~~~~~~~~~~~~~~~~~~~~ + +One powerful feature of Sphinx is the ability to seamlessly add +:ref:`cross-references ` to specific parts of the documentation: +a document, a section, a figure, a code object, etc. This tutorial is full of +them! + +To add a straightforward cross-reference, write this sentence right after the +introduction paragraph in ``index.rst``: + +.. code-block:: rest + + Check out the :doc:`usage` section for further information. + +The :rst:role:`doc` role you used automatically references a specific document +in the project, in this case the ``usage.rst`` you created earlier. + +Alternatively, you can also add a cross-reference to an arbitrary part of the +project. For that, you need to use the :rst:role:`ref` role, and add an +explicit *label* that can act as a target. + +For example, to reference the "Installation" subsection, add a label right +before the heading, as follows: + +.. code-block:: rest + + Usage + ===== + + .. _installation: + + Installation + ------------ + + ... + +And make the sentence you added in ``index.rst`` look like this: + +.. code-block:: rest + + Check out the :doc:`usage` section for further information, including how to + :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 +cross-reference to. Both the ``:doc:`` and the ``:ref:`` roles will be rendered +as hyperlinks in the HTML documentation. + Where to go from here --------------------- From 5a057d3da1fdae1e8393cb0fe6f7a15aa9be8b2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 17 Jun 2021 01:01:34 +0200 Subject: [PATCH 08/30] Actually use new theme --- 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 c4de85cc52b..0d215424945 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -299,7 +299,7 @@ its value as follows: # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # - html_theme = 'alabaster' + html_theme = 'furo' With this change, you will notice that your HTML documentation has now a new appearance: From fb236053ab0eb71aa9b16848f7f453e709e56d5c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 21 Jun 2021 06:58:43 +0200 Subject: [PATCH 09/30] Apply style suggestions from code review Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> --- doc/tutorial/index.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 0d215424945..b81445d3496 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -280,7 +280,7 @@ Using a third-party theme ~~~~~~~~~~~~~~~~~~~~~~~~~ Themes, on the other hand, are a particular class of extensions that allow you -to customize the appearance of your documentation. Again, Sphinx has several +to customize the appearance of your documentation. Sphinx has several :ref:`built-in themes `, and there are also third-party ones. For example, to use the `Furo `_ third-party theme @@ -355,9 +355,8 @@ styles, which means that, by using ``---`` for the "Installation" section after ``===`` for the "Usage" section, you have declared "Installation" to be a *subsection* of "Usage". -In addition, add a ``toctree`` :ref:`directive ` at the end -of ``index.rst`` including the document you just created, -as follows: +To complete the process, add a ``toctree`` :ref:`directive ` at +the end of ``index.rst`` including the document you just created, as follows: .. code-block:: rest @@ -390,7 +389,7 @@ One powerful feature of Sphinx is the ability to seamlessly add a document, a section, a figure, a code object, etc. This tutorial is full of them! -To add a straightforward cross-reference, write this sentence right after the +To add a cross-reference, write this sentence right after the introduction paragraph in ``index.rst``: .. code-block:: rest @@ -408,6 +407,7 @@ For example, to reference the "Installation" subsection, add a label right before the heading, as follows: .. code-block:: rest + :emphasize-lines: 4 Usage ===== From 6f71c7bd7ed6593a4dd2d2de126b83ed89021b0b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 21 Jun 2021 07:09:19 +0200 Subject: [PATCH 10/30] Use absolute links for Sphinx documentation references --- 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 b81445d3496..186beff8cf1 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -247,7 +247,7 @@ Enabling a built-in extension ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In addition to these configuration values, you can customize Sphinx even more -by using :doc:`extensions <../usage/extensions/index>`. Sphinx ships several +by using :doc:`extensions `. Sphinx ships several :ref:`built-in ones `, and there are many more :ref:`maintained by the community `. From e75f31ad47155d77db6a370f87732c9df6ff4649 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 21 Jun 2021 07:11:22 +0200 Subject: [PATCH 11/30] Add link to third-party sphinx-themes --- doc/tutorial/index.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 186beff8cf1..e98e718e144 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -281,7 +281,8 @@ Using a third-party theme Themes, on the other hand, are a particular class of extensions that allow you to customize the appearance of your documentation. Sphinx has several -:ref:`built-in themes `, and there are also third-party ones. +:ref:`built-in themes `, and there are also `third-party +ones `_. For example, to use the `Furo `_ third-party theme in your HTML documentation, first you will need to install it with ``pip`` on From d08c3677d12f80bcbcaff22f4537ae5e7fc14030 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 21 Jun 2021 07:30:02 +0200 Subject: [PATCH 12/30] Avoid reference to earlier content --- doc/tutorial/index.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index e98e718e144..94878548f6b 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -318,10 +318,11 @@ Narrative documentation in Sphinx Inserting documents in the project hierarchy ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -As discussed at the beginning, ``index.rst`` is the :term:`master document`, -whose main function is to serve as a welcome page and to contain the root of -the "table of contents tree" (or *toctree*). Sphinx allows you to assemble -a project from different files, which is helpful when the project grows. +The file ``index.rst`` created by ``sphinx-quickstart`` is the :term:`master +document`, whose main function is to serve as a welcome page and to contain the +root of the "table of contents tree" (or *toctree*). Sphinx allows you to +assemble a project from different files, which is helpful when the project +grows. As an example, create a new file ``docs/source/usage.rst`` (next to ``index.rst``) with these contents: From 3fcaa172db8eccdd97c01a49102f7a95124fbbcf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 21 Jun 2021 07:38:51 +0200 Subject: [PATCH 13/30] Move reference to list of Pygments lexers --- doc/tutorial/index.rst | 12 +++--------- doc/usage/restructuredtext/directives.rst | 10 ++++++---- 2 files changed, 9 insertions(+), 13 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 94878548f6b..fe3eaf04564 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -342,15 +342,9 @@ As an example, create a new file ``docs/source/usage.rst`` (next to (.venv) $ pip install lumache This new file contains two :ref:`section ` headers, normal -paragraph text, and a ``code-block`` directive that renders a block of content -as source code, with appropriate syntax highlighting (in this case, generic -``console`` text). - -.. note:: - - You can read `the list of available highlight - languages `_ in the Pygments - documentation. +paragraph text, and a :ref:`code-block ` directive that renders +a block of content as source code, with appropriate syntax highlighting +(in this case, generic ``console`` text). The structure of the document is determined by the succession of heading styles, which means that, by using ``---`` for the "Installation" section diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index 24f3af9d8bf..329bdef5d11 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -488,6 +488,8 @@ __ https://pygments.org/docs/lexers .. versionadded:: 2.1 +.. _rst-code-block: + .. rst:directive:: .. code-block:: [language] Example:: @@ -497,10 +499,10 @@ __ https://pygments.org/docs/lexers Some Ruby code. The directive's alias name :rst:dir:`sourcecode` works as well. This - directive takes a language name as an argument. It can be any lexer alias - supported by Pygments. If it is not given, the setting of - :rst:dir:`highlight` directive will be used. If not set, - :confval:`highlight_language` will be used. + directive takes a language name as an argument. It can be `any lexer alias + supported by Pygments `_. If it is not + given, the setting of :rst:dir:`highlight` directive will be used. + If not set, :confval:`highlight_language` will be used. .. versionchanged:: 2.0 The ``language`` argument becomes optional. From 8377a550a27a22b1a292fe33a22e1a32a95fe5e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 21 Jun 2021 07:46:13 +0200 Subject: [PATCH 14/30] Simplify out-of-toctree warning --- doc/tutorial/index.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index fe3eaf04564..f42bbee0cc9 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -371,11 +371,9 @@ just created. Neat! .. warning:: - Every document should belong to a *toctree*. Otherwise, Sphinx will emit a - ``WARNING: document isn't included in any toctree``, and the end result - will depend on the builder. For the HTML builder, the page will not be - linked from anywhere (therefore it will not be discoverable), whereas for - the PDF builder, it will not be included at all. + Documents outside a *toctree* will result in ``WARNING: document isn't + included in any toctree`` messages during the build process, and will be + unreachable for users. Adding cross-references ~~~~~~~~~~~~~~~~~~~~~~~ From 0581a17ca6ee1f6b1b1292536372a82908bfd2bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 21 Jun 2021 08:02:21 +0200 Subject: [PATCH 15/30] Clarify this is about HTML themes --- 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 f42bbee0cc9..d4a5ad97d0d 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -276,8 +276,8 @@ durations report at the end of the console output, like this one: ====================== slowest reading durations ======================= 0.042 temp/source/index -Using a third-party theme -~~~~~~~~~~~~~~~~~~~~~~~~~ +Using a third-party HTML theme +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Themes, on the other hand, are a particular class of extensions that allow you to customize the appearance of your documentation. Sphinx has several @@ -285,7 +285,7 @@ to customize the appearance of your documentation. Sphinx has several ones `_. For example, to use the `Furo `_ third-party theme -in your HTML documentation, first you will need to install it with ``pip`` on +in your HTML documentation, first you will need to install it with ``pip`` in your Python virtual environment, like this: .. code-block:: console From 35714269e86b5bea09139143849b21c45e124f70 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 21 Jun 2021 08:09:26 +0200 Subject: [PATCH 16/30] Add text representation of the document structure --- doc/tutorial/index.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index d4a5ad97d0d..0657dda3295 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -364,10 +364,16 @@ the end of ``index.rst`` including the document you just created, as follows: usage This step inserts that document in the root of the *toctree*, so now it belongs -to the structure of your project. If you export the documentation to HTML -running ``make html``, you will see that the ``toctree`` gets rendered as a -list of hyperlinks, and this allows you to navigate to the new page you -just created. Neat! +to the structure of your project, which so far looks like this: + +.. code-block:: text + + index + └── usage + +If you export the documentation to HTML running ``make html``, you will see +that the ``toctree`` gets rendered as a list of hyperlinks, and this allows you +to navigate to the new page you just created. Neat! .. warning:: From e865c526bb4c6601ed8d0726bc15d79fefa1ba4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 21 Jun 2021 08:17:30 +0200 Subject: [PATCH 17/30] Add filenames as captions for relevant code blocks --- doc/tutorial/index.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 0657dda3295..505c5f874e5 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -40,6 +40,7 @@ In a new directory, create a file called ``README.rst`` with the following content. .. code-block:: rest + :caption: README.rst Lumache ======= @@ -162,6 +163,7 @@ is written in reStructuredText, a powerful markup language. Modify the file as follows: .. code-block:: rest + :caption: docs/source/index.rst Welcome to Lumache's documentation! =================================== @@ -256,6 +258,7 @@ locate the ``extensions`` list in your ``conf.py`` and add one element as follows: .. code-block:: python + :caption: docs/source/conf.py # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -296,6 +299,7 @@ And then, locate the ``html_theme`` variable on your ``conf.py`` and replace its value as follows: .. code-block:: python + :caption: docs/source/conf.py # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. @@ -328,6 +332,7 @@ As an example, create a new file ``docs/source/usage.rst`` (next to ``index.rst``) with these contents: .. code-block:: rest + :caption: docs/source/usage.rst Usage ===== @@ -355,6 +360,7 @@ To complete the process, add a ``toctree`` :ref:`directive ` at the end of ``index.rst`` including the document you just created, as follows: .. code-block:: rest + :caption: docs/source/index.rst Contents -------- @@ -393,6 +399,7 @@ To add a cross-reference, write this sentence right after the introduction paragraph in ``index.rst``: .. code-block:: rest + :caption: docs/source/index.rst Check out the :doc:`usage` section for further information. @@ -407,6 +414,7 @@ For example, to reference the "Installation" subsection, add a label right before the heading, as follows: .. code-block:: rest + :caption: docs/source/usage.rst :emphasize-lines: 4 Usage @@ -422,6 +430,7 @@ before the heading, as follows: And make the sentence you added in ``index.rst`` look like this: .. code-block:: rest + :caption: docs/source/index.rst Check out the :doc:`usage` section for further information, including how to :ref:`install ` the project. From 106346a4ef5711428f289290d7b1c9d5342d1959 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 21 Jun 2021 08:24:10 +0200 Subject: [PATCH 18/30] Make section title more goal-oriented --- doc/tutorial/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 505c5f874e5..57de160062a 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -319,8 +319,8 @@ appearance: Narrative documentation in Sphinx --------------------------------- -Inserting documents in the project hierarchy -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Structuring your documentation across multiple pages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The file ``index.rst`` created by ``sphinx-quickstart`` is the :term:`master document`, whose main function is to serve as a welcome page and to contain the From a3478eb2d01cb7e210d4a3faa0a04ed5606d57e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 21 Jun 2021 14:25:17 +0200 Subject: [PATCH 19/30] Update doc/tutorial/index.rst Co-authored-by: Manuel Kaufmann --- 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 57de160062a..68fbb5dec00 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -209,7 +209,7 @@ e-book in EPUB format, run this command from the ``docs`` directory: (.venv) $ make epub After that, you will see the files corresponding to the e-book under -``docs/build/html/``. You can either open ``Lumache.epub`` with an +``docs/build/epub/``. You can either open ``Lumache.epub`` with an EPUB-compatible e-book viewer, like `Calibre `_, or preview ``index.xhtml`` on a web browser. From 5f41044abb6802291989de8b34cd587b7e79ec1c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Tue, 22 Jun 2021 15:20:06 +0200 Subject: [PATCH 20/30] Tone down LaTeX info to "note" 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 68fbb5dec00..1e600e637a4 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -233,7 +233,7 @@ With this configuration value, and after running ``make epub`` again, you will notice that URLs appear now as footnotes, which avoids cluttering the text. Sweet! -.. warning:: +.. note:: Generating a PDF using Sphinx can be done running ``make latexpdf``, provided that the system has a working :math:`\LaTeX` installation, From c9d2a73d93cd933616a93684a7b7ab7ce141e7f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Tue, 22 Jun 2021 15:26:59 +0200 Subject: [PATCH 21/30] Rename to root document --- doc/glossary.rst | 2 +- doc/templating.rst | 2 +- doc/tutorial/index.rst | 4 ++-- doc/usage/advanced/setuptools.rst | 2 +- doc/usage/builders/index.rst | 2 +- doc/usage/quickstart.rst | 4 ++-- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/glossary.rst b/doc/glossary.rst index 87b7014b6fa..f989df1aeec 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -73,7 +73,7 @@ Glossary For more information, refer to :doc:`/usage/extensions/index`. - master document + root document The document that contains the root :rst:dir:`toctree` directive. object diff --git a/doc/templating.rst b/doc/templating.rst index 0e9d38adda7..b253723198f 100644 --- a/doc/templating.rst +++ b/doc/templating.rst @@ -115,7 +115,7 @@ The following blocks exist in the ``layout.html`` template: ``rootrellink``, ``relbaritems`` Inside the relbar there are three sections: The ``rootrellink``, the links from the documentation and the custom ``relbaritems``. The ``rootrellink`` - is a block that by default contains a list item pointing to the master + is a block that by default contains a list item pointing to the root document by default, the ``relbaritems`` is an empty block. If you override them to add extra links into the bar make sure that they are list items and end with the :data:`reldelim1`. diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 1e600e637a4..8ab1fc28783 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -128,7 +128,7 @@ The purpose of each of these files is: as some extra configuration keys. ``source/index.rst`` - The :term:`master document` of the project, which serves as welcome page and + The :term:`root document` of the project, which serves as welcome page and contains the root of the "table of contents tree" (or *toctree*). Thanks to this bootstrapping step, you already have everything needed to render @@ -322,7 +322,7 @@ Narrative documentation in Sphinx Structuring your documentation across multiple pages ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The file ``index.rst`` created by ``sphinx-quickstart`` is the :term:`master +The file ``index.rst`` created by ``sphinx-quickstart`` is the :term:`root document`, whose main function is to serve as a welcome page and to contain the root of the "table of contents tree" (or *toctree*). Sphinx allows you to assemble a project from different files, which is helpful when the project diff --git a/doc/usage/advanced/setuptools.rst b/doc/usage/advanced/setuptools.rst index f4dfb7f669d..7f993e10c54 100644 --- a/doc/usage/advanced/setuptools.rst +++ b/doc/usage/advanced/setuptools.rst @@ -164,7 +164,7 @@ Options for setuptools integration .. setuptools-confval:: link-index - A boolean that ensures index.html will be linked to the master doc. Default + A boolean that ensures index.html will be linked to the root doc. Default is false. This can also be set by passing the `-i` flag to ``setup.py``: diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst index 74853fee971..4d5315227d2 100644 --- a/doc/usage/builders/index.rst +++ b/doc/usage/builders/index.rst @@ -51,7 +51,7 @@ The builder's "name" must be given to the **-b** command-line option of This is an HTML builder that combines the whole project in one output file. (Obviously this only works with smaller projects.) The file is named like - the master document. No indices will be generated. + the root document. No indices will be generated. .. autoattribute:: name diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst index 83b5211bd67..ec36f5df9b0 100644 --- a/doc/usage/quickstart.rst +++ b/doc/usage/quickstart.rst @@ -48,8 +48,8 @@ Defining document structure --------------------------- Let's assume you've run :program:`sphinx-quickstart`. It created a source -directory with :file:`conf.py` and a master document, :file:`index.rst`. The -main function of the :term:`master document` is to serve as a welcome page, and +directory with :file:`conf.py` and a root document, :file:`index.rst`. The +main function of the :term:`root document` is to serve as a welcome page, and to contain the root of the "table of contents tree" (or *toctree*). This is one of the main things that Sphinx adds to reStructuredText, a way to connect multiple files to a single hierarchy of documents. From 15fe52dce6439d0e4c81d1a2d8fadc6401cae1e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Tue, 22 Jun 2021 15:37:30 +0200 Subject: [PATCH 22/30] Separate extensions and themes more clearly --- doc/tutorial/index.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 8ab1fc28783..936bfa5496b 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -242,8 +242,11 @@ Sweet! and in general LaTeX requires careful configuration in some cases, so PDF generation is out of scope for this tutorial. -More Sphinx customization using extensions ------------------------------------------- +More Sphinx customization +------------------------- + +There are two main ways to customize your documentation beyond what is possible +with core Sphinx: extensions and themes. Enabling a built-in extension ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -282,10 +285,9 @@ durations report at the end of the console output, like this one: Using a third-party HTML theme ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Themes, on the other hand, are a particular class of extensions that allow you -to customize the appearance of your documentation. Sphinx has several -:ref:`built-in themes `, and there are also `third-party -ones `_. +Themes, on the other hand, are a way to customize the appearance of your +documentation. Sphinx has several :ref:`built-in themes `, and +there are also `third-party ones `_. For example, to use the `Furo `_ third-party theme in your HTML documentation, first you will need to install it with ``pip`` in From 013e67f4fd9b1317ce4697d6462437098c4ff927 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Tue, 22 Jun 2021 15:44:52 +0200 Subject: [PATCH 23/30] Clarify what happens if no title is used in the :ref: --- doc/tutorial/index.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 936bfa5496b..24d56f28c2f 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -440,7 +440,9 @@ And make the sentence you added in ``index.rst`` look like this: 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 -cross-reference to. Both the ``:doc:`` and the ``:ref:`` roles will be rendered +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. Where to go from here From 13831572d564a811c4d90839350e73703d34293f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 5 Jul 2021 09:11:47 +0200 Subject: [PATCH 24/30] Keep old name for root document in the glossary --- doc/glossary.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/glossary.rst b/doc/glossary.rst index f989df1aeec..ca12067c490 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -73,9 +73,12 @@ Glossary For more information, refer to :doc:`/usage/extensions/index`. - root document + master document The document that contains the root :rst:dir:`toctree` directive. + root document + Same as :term:`master document`. + object The basic building block of Sphinx documentation. Every "object directive" (e.g. :rst:dir:`function` or :rst:dir:`object`) creates such a From d5f452a81f3d2cd0fac35fe4d3ead08d66922ab8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 5 Jul 2021 09:12:40 +0200 Subject: [PATCH 25/30] Remove redundant local table of contents --- doc/tutorial/index.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 24d56f28c2f..ae9a82000dd 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -27,9 +27,6 @@ a basic understanding of how it works, as well as a working Python installation for development, since you will use *Python virtual environments* to create the project. -.. contents:: Contents - :local: - Getting started --------------- From 74e565f99bcbe664b8d1cb7641abd1b0c64dd2e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 5 Jul 2021 09:21:55 +0200 Subject: [PATCH 26/30] Consistent use of "build documentation" --- doc/tutorial/index.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index ae9a82000dd..b3e388258f9 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -150,8 +150,8 @@ There we go! You created your first HTML documentation using Sphinx. First steps to document your project using Sphinx ------------------------------------------------- -Converting your documentation to HTML -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Building your HTML documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``index.rst`` file that ``sphinx-quickstart`` created has some content already, and it gets rendered as the front page of your HTML documentation. It @@ -194,12 +194,12 @@ as before, or leverage the convenience script as follows: After running this command, you will see that ``index.html`` reflects the new changes! -Exporting your documentation to other formats -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Building your documentation in other formats +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sphinx supports a variety of formats apart from HTML, including PDF, EPUB, -:ref:`and more `. For example, to build your documentation as an -e-book in EPUB format, run this command from the ``docs`` directory: +:ref:`and more `. For example, to build your documentation +in EPUB format, run this command from the ``docs`` directory: .. code-block:: console @@ -376,7 +376,7 @@ to the structure of your project, which so far looks like this: index └── usage -If you export the documentation to HTML running ``make html``, you will see +If you build the HTML documentation running ``make html``, you will see that the ``toctree`` gets rendered as a list of hyperlinks, and this allows you to navigate to the new page you just created. Neat! From 50bd1c3967fae76e36a5b1d386e3cbad637f6da1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 5 Jul 2021 09:22:14 +0200 Subject: [PATCH 27/30] Remove unnecessary label --- doc/tutorial/index.rst | 2 +- doc/usage/restructuredtext/directives.rst | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index b3e388258f9..7a7a310c394 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -346,7 +346,7 @@ As an example, create a new file ``docs/source/usage.rst`` (next to (.venv) $ pip install lumache This new file contains two :ref:`section ` headers, normal -paragraph text, and a :ref:`code-block ` directive that renders +paragraph text, and a :rst:dir:`code-block` directive that renders a block of content as source code, with appropriate syntax highlighting (in this case, generic ``console`` text). diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index 329bdef5d11..2a9743e948d 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -488,8 +488,6 @@ __ https://pygments.org/docs/lexers .. versionadded:: 2.1 -.. _rst-code-block: - .. rst:directive:: .. code-block:: [language] Example:: From f303a4a9ed9196cd767f127aff292d9bcfd28514 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 5 Jul 2021 09:25:05 +0200 Subject: [PATCH 28/30] Consistent use of "rst" for syntax highlight --- doc/tutorial/index.rst | 14 +++++++------- doc/usage/quickstart.rst | 8 ++++---- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 7a7a310c394..12ae10e11c0 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -36,7 +36,7 @@ Setting up your project and development environment In a new directory, create a file called ``README.rst`` with the following content. -.. code-block:: rest +.. code-block:: rst :caption: README.rst Lumache @@ -159,7 +159,7 @@ is written in reStructuredText, a powerful markup language. Modify the file as follows: -.. code-block:: rest +.. code-block:: rst :caption: docs/source/index.rst Welcome to Lumache's documentation! @@ -330,7 +330,7 @@ grows. As an example, create a new file ``docs/source/usage.rst`` (next to ``index.rst``) with these contents: -.. code-block:: rest +.. code-block:: rst :caption: docs/source/usage.rst Usage @@ -358,7 +358,7 @@ be a *subsection* of "Usage". To complete the process, add a ``toctree`` :ref:`directive ` at the end of ``index.rst`` including the document you just created, as follows: -.. code-block:: rest +.. code-block:: rst :caption: docs/source/index.rst Contents @@ -397,7 +397,7 @@ them! To add a cross-reference, write this sentence right after the introduction paragraph in ``index.rst``: -.. code-block:: rest +.. code-block:: rst :caption: docs/source/index.rst Check out the :doc:`usage` section for further information. @@ -412,7 +412,7 @@ explicit *label* that can act as a target. For example, to reference the "Installation" subsection, add a label right before the heading, as follows: -.. code-block:: rest +.. code-block:: rst :caption: docs/source/usage.rst :emphasize-lines: 4 @@ -428,7 +428,7 @@ before the heading, as follows: And make the sentence you added in ``index.rst`` look like this: -.. code-block:: rest +.. code-block:: rst :caption: docs/source/index.rst Check out the :doc:`usage` section for further information, including how to diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst index ec36f5df9b0..8644a00213d 100644 --- a/doc/usage/quickstart.rst +++ b/doc/usage/quickstart.rst @@ -74,14 +74,14 @@ multiple files to a single hierarchy of documents. The ``toctree`` directive initially is empty, and looks like so: -.. code-block:: rest +.. code-block:: rst .. toctree:: :maxdepth: 2 You add documents listing them in the *content* of the directive: -.. code-block:: rest +.. code-block:: rst .. toctree:: :maxdepth: 2 @@ -172,7 +172,7 @@ The most prominent domain is the Python domain. For example, to document Python's built-in function ``enumerate()``, you would add this to one of your source files. -.. code-block:: restructuredtext +.. code-block:: rst .. py:function:: enumerate(sequence[, start=0]) @@ -193,7 +193,7 @@ given, each in its own line. The Python domain also happens to be the default domain, so you don't need to prefix the markup with the domain name. -.. code-block:: restructuredtext +.. code-block:: rst .. function:: enumerate(sequence[, start=0]) From 6f9bc6e7e5d571adec4bad942e8d2f4d3a71a1be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 5 Jul 2021 09:30:30 +0200 Subject: [PATCH 29/30] Use "builtin" for extensions label as it is done for themes --- doc/tutorial/index.rst | 4 ++-- doc/usage/extensions/index.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 12ae10e11c0..b173a8ed9a2 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -250,7 +250,7 @@ Enabling a built-in extension In addition to these configuration values, you can customize Sphinx even more by using :doc:`extensions `. Sphinx ships several -:ref:`built-in ones `, and there are many more +:ref:`builtin ones `, and there are many more :ref:`maintained by the community `. For example, to enable the :mod:`sphinx.ext.duration` extension, @@ -283,7 +283,7 @@ Using a third-party HTML theme ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Themes, on the other hand, are a way to customize the appearance of your -documentation. Sphinx has several :ref:`built-in themes `, and +documentation. Sphinx has several :ref:`builtin themes `, and there are also `third-party ones `_. For example, to use the `Furo `_ third-party theme diff --git a/doc/usage/extensions/index.rst b/doc/usage/extensions/index.rst index 389d9ccbd9e..37d71c5034f 100644 --- a/doc/usage/extensions/index.rst +++ b/doc/usage/extensions/index.rst @@ -10,7 +10,7 @@ This chapter describes the extensions bundled with Sphinx. For the API documentation on writing your own extension, refer to :ref:`dev-extensions`. -.. _built-in-extensions: +.. _builtin-extensions: Built-in extensions ------------------- From cb846a39e0582ade5b852b425c9e047bde995a06 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 5 Jul 2021 09:35:01 +0200 Subject: [PATCH 30/30] Add link to docutils docs --- doc/tutorial/index.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index b173a8ed9a2..6ff26869516 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -407,7 +407,9 @@ in the project, in this case the ``usage.rst`` you created earlier. Alternatively, you can also add a cross-reference to an arbitrary part of the project. For that, you need to use the :rst:role:`ref` role, and add an -explicit *label* that can act as a target. +explicit *label* that acts as `a target`__. + +__ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets For example, to reference the "Installation" subsection, add a label right before the heading, as follows: