From f152680bfb9ee25f517346f3790a188732388a31 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 9 Aug 2021 14:02:31 +0200 Subject: [PATCH] Split tutorial in several files --- doc/tutorial/end.rst | 6 + doc/tutorial/first-steps.rst | 91 +++++ doc/tutorial/getting-started.rst | 119 ++++++ doc/tutorial/index.rst | 428 +-------------------- doc/tutorial/more-sphinx-customization.rst | 75 ++++ doc/tutorial/narrative-documentation.rst | 128 ++++++ 6 files changed, 425 insertions(+), 422 deletions(-) create mode 100644 doc/tutorial/end.rst create mode 100644 doc/tutorial/first-steps.rst create mode 100644 doc/tutorial/getting-started.rst create mode 100644 doc/tutorial/more-sphinx-customization.rst create mode 100644 doc/tutorial/narrative-documentation.rst 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 `. 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 `_ 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 + `) + +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 `. 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 `_, +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! + +.. 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 `_ 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 - `) - -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 `. 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 `_, -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! - -.. 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 `. Sphinx ships several -:ref:`builtin 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 - :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 `, 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 -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 ` 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 ` 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 ` 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 ` 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. 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 `. + 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 `. Sphinx ships several +:ref:`builtin 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 + :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 `, 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 +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 ` 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 ` 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 ` 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 ` 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. 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.