Merge pull request #9540 from astrojuanlu/new-tutorial-split

Split tutorial in several files

6 files changed, 425 insertions, 422 deletions

diff --git a/doc/tutorial/end.rst b/doc/tutorial/end.rst
new file mode 100644
index 000000000..ba96abca0
--- /dev/null
+++ b/doc/tutorial/end.rst
@@ -0,0 +1,6 @@
+Where to go from here
+=====================
+
+This tutorial covered the very first steps to create a documentation project
+with Sphinx.  To continue learning more about Sphinx, check out the :ref:`rest
+of the documentation <contents>`.
diff --git a/doc/tutorial/first-steps.rst b/doc/tutorial/first-steps.rst
new file mode 100644
index 000000000..791ee38f5
--- /dev/null
+++ b/doc/tutorial/first-steps.rst
@@ -0,0 +1,91 @@
+First steps to document your project using Sphinx
+=================================================
+
+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
+is written in reStructuredText, a powerful markup language.
+
+Modify the file as follows:
+
+.. code-block:: rst
+   :caption: docs/source/index.rst
+
+   Welcome to Lumache's documentation!
+   ===================================
+
+   **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
+   creates recipes mixing random ingredients.  It pulls data from the `Open Food
+   Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
+   *intuitive* API.
+
+   .. note::
+
+      This project is under active development.
+
+This showcases several features of the reStructuredText syntax, including:
+
+- a **section header** using ``===`` for the underline,
+- two examples of :ref:`rst-inline-markup`: ``**strong emphasis**`` (typically
+  bold) and ``*emphasis*`` (typically italics),
+- an **inline external link**,
+- and a ``note`` **admonition** (one of the available :ref:`directives
+  <rst-directives>`)
+
+Now to render it with the new content, you can use the ``sphinx-build`` command
+as before, or leverage the convenience script as follows:
+
+.. code-block:: console
+
+   (.venv) $ cd docs
+   (.venv) $ make html
+
+After running this command, you will see that ``index.html`` reflects the new
+changes!
+
+Building your documentation in other formats
+--------------------------------------------
+
+Sphinx supports a variety of formats apart from HTML, including PDF, EPUB,
+:ref:`and more <builders>`.  For example, to build your documentation
+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/epub/``.  You can either open ``Lumache.epub`` with an
+EPUB-compatible e-book viewer, like `Calibre <https://calibre-ebook.com/>`_,
+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 <epub-options>`.  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!
+
+.. note::
+
+   Generating a PDF using Sphinx can be done running ``make latexpdf``,
+   provided that the system has a working 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.
diff --git a/doc/tutorial/getting-started.rst b/doc/tutorial/getting-started.rst
new file mode 100644
index 000000000..ccfa0952e
--- /dev/null
+++ b/doc/tutorial/getting-started.rst
@@ -0,0 +1,119 @@
+Getting started
+===============
+
+Setting up your project and development environment
+---------------------------------------------------
+
+In a new directory, create a file called ``README.rst`` with the following
+content.
+
+.. code-block:: rst
+   :caption: README.rst
+
+   Lumache
+   =======
+
+   **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
+   creates recipes mixing random ingredients.
+
+It is a good moment to create a Python virtual environment and install the
+required tools.  For that, open a command line terminal, ``cd`` into the
+directory you just created, and run the following commands:
+
+.. code-block:: console
+
+   $ python -m venv .venv
+   $ source .venv/bin/activate
+   (.venv) $ python -m pip install sphinx
+
+.. note::
+
+   The installation method used above is described in more detail in
+   :ref:`install-pypi`.  For the rest of this tutorial, the instructions will
+   assume a Python virtual environment.
+
+If you executed these instructions correctly, you should have the Sphinx command
+line tools available.  You can do a basic verification running this command:
+
+.. code-block:: console
+
+   (.venv) $ sphinx-build --version
+   sphinx-build 4.0.2
+
+If you see a similar output, you are on the right path!
+
+Creating the documentation layout
+---------------------------------
+
+Then from the command line, run the following command:
+
+.. code-block:: console
+
+   (.venv) $ sphinx-quickstart docs
+
+This will present to you a series of questions required to create the basic
+directory and configuration layout for your project inside the ``docs`` folder.
+To proceed, answer each question as follows:
+
+- ``> Separate source and build directories (y/n) [n]``: Write "``y``" (without
+  quotes) and press :kbd:`Enter`.
+- ``> Project name``: Write "``Lumache``" (without quotes) and press
+  :kbd:`Enter`.
+- ``> Author name(s)``: Write "``Graziella``" (without quotes) and press
+  :kbd:`Enter`.
+- ``> Project release []``: Write "``0.1``" (without quotes) and press
+  :kbd:`Enter`.
+- ``> Project language [en]``: Leave it empty (the default, English) and press
+  :kbd:`Enter`.
+
+After the last question, you will see the new ``docs`` directory with the
+following content.
+
+.. code-block:: text
+
+   docs
+   ├── build
+   ├── make.bat
+   ├── Makefile
+   └── source
+      ├── conf.py
+      ├── index.rst
+      ├── _static
+      └── _templates
+
+The purpose of each of these files is:
+
+``build/``
+  An empty directory (for now) that will hold the rendered documentation.
+
+``make.bat`` and ``Makefile``
+  Convenience scripts to simplify some common Sphinx operations, such as
+  rendering the content.
+
+``source/conf.py``
+  A Python script holding the configuration of the Sphinx project.  It contains
+  the project name and release you specified to ``sphinx-quickstart``, as well
+  as some extra configuration keys.
+
+``source/index.rst``
+  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
+the documentation as HTML for the first time.  To do that, run this command:
+
+.. code-block:: console
+
+   (.venv) $ sphinx-build -b html docs/source/ docs/build/html
+
+And finally, open ``docs/build/html/index.html`` in your browser.  You should see
+something like this:
+
+.. 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.
diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst
index 51409a6b0..06179f9d0 100644
--- a/doc/tutorial/index.rst
+++ b/doc/tutorial/index.rst
@@ -27,426 +27,10 @@ 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.
 
-Getting started
----------------
+.. toctree::
 
-Setting up your project and development environment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In a new directory, create a file called ``README.rst`` with the following
-content.
-
-.. code-block:: rst
-   :caption: README.rst
-
-   Lumache
-   =======
-
-   **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
-   creates recipes mixing random ingredients.
-
-It is a good moment to create a Python virtual environment and install the
-required tools.  For that, open a command line terminal, ``cd`` into the
-directory you just created, and run the following commands:
-
-.. code-block:: console
-
-   $ python -m venv .venv
-   $ source .venv/bin/activate
-   (.venv) $ python -m pip install sphinx
-
-.. note::
-
-   The installation method used above is described in more detail in
-   :ref:`install-pypi`.  For the rest of this tutorial, the instructions will
-   assume a Python virtual environment.
-
-If you executed these instructions correctly, you should have the Sphinx command
-line tools available.  You can do a basic verification running this command:
-
-.. code-block:: console
-
-   (.venv) $ sphinx-build --version
-   sphinx-build 4.0.2
-
-If you see a similar output, you are on the right path!
-
-Creating the documentation layout
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Then from the command line, run the following command:
-
-.. code-block:: console
-
-   (.venv) $ sphinx-quickstart docs
-
-This will present to you a series of questions required to create the basic
-directory and configuration layout for your project inside the ``docs`` folder.
-To proceed, answer each question as follows:
-
-- ``> Separate source and build directories (y/n) [n]``: Write "``y``" (without
-  quotes) and press :kbd:`Enter`.
-- ``> Project name``: Write "``Lumache``" (without quotes) and press
-  :kbd:`Enter`.
-- ``> Author name(s)``: Write "``Graziella``" (without quotes) and press
-  :kbd:`Enter`.
-- ``> Project release []``: Write "``0.1``" (without quotes) and press
-  :kbd:`Enter`.
-- ``> Project language [en]``: Leave it empty (the default, English) and press
-  :kbd:`Enter`.
-
-After the last question, you will see the new ``docs`` directory with the
-following content.
-
-.. code-block:: text
-
-   docs
-   ├── build
-   ├── make.bat
-   ├── Makefile
-   └── source
-      ├── conf.py
-      ├── index.rst
-      ├── _static
-      └── _templates
-
-The purpose of each of these files is:
-
-``build/``
-  An empty directory (for now) that will hold the rendered documentation.
-
-``make.bat`` and ``Makefile``
-  Convenience scripts to simplify some common Sphinx operations, such as
-  rendering the content.
-
-``source/conf.py``
-  A Python script holding the configuration of the Sphinx project.  It contains
-  the project name and release you specified to ``sphinx-quickstart``, as well
-  as some extra configuration keys.
-
-``source/index.rst``
-  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
-the documentation as HTML for the first time.  To do that, run this command:
-
-.. code-block:: console
-
-   (.venv) $ sphinx-build -b html docs/source/ docs/build/html
-
-And finally, open ``docs/build/html/index.html`` in your browser.  You should see
-something like this:
-
-.. 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.
-
-First steps to document your project using Sphinx
--------------------------------------------------
-
-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
-is written in reStructuredText, a powerful markup language.
-
-Modify the file as follows:
-
-.. code-block:: rst
-   :caption: docs/source/index.rst
-
-   Welcome to Lumache's documentation!
-   ===================================
-
-   **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
-   creates recipes mixing random ingredients.  It pulls data from the `Open Food
-   Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
-   *intuitive* API.
-
-   .. note::
-
-      This project is under active development.
-
-This showcases several features of the reStructuredText syntax, including:
-
-- a **section header** using ``===`` for the underline,
-- two examples of :ref:`rst-inline-markup`: ``**strong emphasis**`` (typically
-  bold) and ``*emphasis*`` (typically italics),
-- an **inline external link**,
-- and a ``note`` **admonition** (one of the available :ref:`directives
-  <rst-directives>`)
-
-Now to render it with the new content, you can use the ``sphinx-build`` command
-as before, or leverage the convenience script as follows:
-
-.. code-block:: console
-
-   (.venv) $ cd docs
-   (.venv) $ make html
-
-After running this command, you will see that ``index.html`` reflects the new
-changes!
-
-Building your documentation in other formats
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Sphinx supports a variety of formats apart from HTML, including PDF, EPUB,
-:ref:`and more <builders>`.  For example, to build your documentation
-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/epub/``.  You can either open ``Lumache.epub`` with an
-EPUB-compatible e-book viewer, like `Calibre <https://calibre-ebook.com/>`_,
-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 <epub-options>`.  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!
-
-.. note::
-
-   Generating a PDF using Sphinx can be done running ``make latexpdf``,
-   provided that the system has a working 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.
-
-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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In addition to these configuration values, you can customize Sphinx even more
-by using :doc:`extensions </usage/extensions/index>`.  Sphinx ships several
-:ref:`builtin ones <builtin-extensions>`, and there are many more
-:ref:`maintained by the community <third-party-extensions>`.
-
-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
-   :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
-   # 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 HTML theme
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Themes, on the other hand, are a way to customize the appearance of your
-documentation.  Sphinx has several :ref:`builtin themes <builtin-themes>`, and
-there are also `third-party ones <https://sphinx-themes.org/>`_.
-
-For example, to use the `Furo <https://pradyunsg.me/furo/>`_ third-party theme
-in your HTML documentation, first you will need to install it with ``pip`` in
-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
-   :caption: docs/source/conf.py
-
-   # The theme to use for HTML and HTML Help pages.  See the documentation for
-   # a list of builtin themes.
-   #
-   html_theme = 'furo'
-
-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
-
-Narrative documentation in Sphinx
----------------------------------
-
-Structuring your documentation across multiple pages
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-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
-grows.
-
-As an example, create a new file ``docs/source/usage.rst`` (next to
-``index.rst``) with these contents:
-
-.. code-block:: rst
-   :caption: docs/source/usage.rst
-
-   Usage
-   =====
-
-   Installation
-   ------------
-
-   To use Lumache, first install it using pip:
-
-   .. code-block:: console
-
-      (.venv) $ pip install lumache
-
-This new file contains two :ref:`section <rst-sections>` headers, normal
-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).
-
-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".
-
-To complete the process, add a ``toctree`` :ref:`directive <rst-directives>` at
-the end of ``index.rst`` including the document you just created, as follows:
-
-.. code-block:: rst
-   :caption: docs/source/index.rst
-
-   Contents
-   --------
-
-   .. toctree::
-
-      usage
-
-This step inserts that document in the root of the *toctree*, so now it belongs
-to the structure of your project, which so far looks like this:
-
-.. code-block:: text
-
-   index
-   └── usage
-
-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!
-
-.. warning::
-
-   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
-~~~~~~~~~~~~~~~~~~~~~~~
-
-One powerful feature of Sphinx is the ability to seamlessly add
-:ref:`cross-references <xref-syntax>` 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 cross-reference, write this sentence right after the
-introduction paragraph in ``index.rst``:
-
-.. code-block:: rst
-   :caption: docs/source/index.rst
-
-   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 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:
-
-.. code-block:: rst
-   :caption: docs/source/usage.rst
-   :emphasize-lines: 4
-
-   Usage
-   =====
-
-   .. _installation:
-
-   Installation
-   ------------
-
-   ...
-
-And make the sentence you added in ``index.rst`` look like this:
-
-.. code-block:: rst
-   :caption: docs/source/index.rst
-
-   Check out the :doc:`usage` section for further information, including how to
-   :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
-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
----------------------
-
-This tutorial covered the very first steps to create a documentation project
-with Sphinx.  To continue learning more about Sphinx, check out the :ref:`rest
-of the documentation <contents>`.
+   getting-started
+   first-steps
+   more-sphinx-customization
+   narrative-documentation
+   end
diff --git a/doc/tutorial/more-sphinx-customization.rst b/doc/tutorial/more-sphinx-customization.rst
new file mode 100644
index 000000000..6a35a6c8c
--- /dev/null
+++ b/doc/tutorial/more-sphinx-customization.rst
@@ -0,0 +1,75 @@
+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
+-----------------------------
+
+In addition to these configuration values, you can customize Sphinx even more
+by using :doc:`extensions </usage/extensions/index>`.  Sphinx ships several
+:ref:`builtin ones <builtin-extensions>`, and there are many more
+:ref:`maintained by the community <third-party-extensions>`.
+
+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
+   :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
+   # 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 HTML theme
+------------------------------
+
+Themes, on the other hand, are a way to customize the appearance of your
+documentation.  Sphinx has several :ref:`builtin themes <builtin-themes>`, and
+there are also `third-party ones <https://sphinx-themes.org/>`_.
+
+For example, to use the `Furo <https://pradyunsg.me/furo/>`_ third-party theme
+in your HTML documentation, first you will need to install it with ``pip`` in
+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
+   :caption: docs/source/conf.py
+
+   # The theme to use for HTML and HTML Help pages.  See the documentation for
+   # a list of builtin themes.
+   #
+   html_theme = 'furo'
+
+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
diff --git a/doc/tutorial/narrative-documentation.rst b/doc/tutorial/narrative-documentation.rst
new file mode 100644
index 000000000..d29db1d77
--- /dev/null
+++ b/doc/tutorial/narrative-documentation.rst
@@ -0,0 +1,128 @@
+Narrative documentation in Sphinx
+=================================
+
+Structuring your documentation across multiple pages
+----------------------------------------------------
+
+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
+grows.
+
+As an example, create a new file ``docs/source/usage.rst`` (next to
+``index.rst``) with these contents:
+
+.. code-block:: rst
+   :caption: docs/source/usage.rst
+
+   Usage
+   =====
+
+   Installation
+   ------------
+
+   To use Lumache, first install it using pip:
+
+   .. code-block:: console
+
+      (.venv) $ pip install lumache
+
+This new file contains two :ref:`section <rst-sections>` headers, normal
+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).
+
+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".
+
+To complete the process, add a ``toctree`` :ref:`directive <rst-directives>` at
+the end of ``index.rst`` including the document you just created, as follows:
+
+.. code-block:: rst
+   :caption: docs/source/index.rst
+
+   Contents
+   --------
+
+   .. toctree::
+
+      usage
+
+This step inserts that document in the root of the *toctree*, so now it belongs
+to the structure of your project, which so far looks like this:
+
+.. code-block:: text
+
+   index
+   └── usage
+
+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!
+
+.. warning::
+
+   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
+-----------------------
+
+One powerful feature of Sphinx is the ability to seamlessly add
+:ref:`cross-references <xref-syntax>` 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 cross-reference, write this sentence right after the
+introduction paragraph in ``index.rst``:
+
+.. code-block:: rst
+   :caption: docs/source/index.rst
+
+   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 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:
+
+.. code-block:: rst
+   :caption: docs/source/usage.rst
+   :emphasize-lines: 4
+
+   Usage
+   =====
+
+   .. _installation:
+
+   Installation
+   ------------
+
+   ...
+
+And make the sentence you added in ``index.rst`` look like this:
+
+.. code-block:: rst
+   :caption: docs/source/index.rst
+
+   Check out the :doc:`usage` section for further information, including how to
+   :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
+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.