sphinx/doc/tutorial/index.rst

.. _tutorial:

===============
Sphinx tutorial
===============

In this tutorial you will build a simple documentation project using Sphinx, and
view it in your browser as HTML.  The project will include narrative,
handwritten documentation, as well as autogenerated API documentation.

The tutorial is aimed towards Sphinx newcomers willing to learn the fundamentals
of how projects are created and structured.  You will create a fictional
software library to generate random food recipes that will serve as a guide
throughout the process, with the objective of properly documenting it.

To showcase Sphinx capabilities for code documentation you will use Python,
which also supports *automatic* documentation generation.

.. note::

   Several other languages are natively supported in Sphinx for *manual* code
   documentation, however they require extensions for *automatic* code
   documentation, like `Breathe <https://breathe.readthedocs.io/>`_.

To follow the instructions you will need access to a Linux-like command line and
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
---------------

Setting up your project and development environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In a new directory, create a file called ``README.rst`` with the following
content.

.. code-block:: rest

   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:`master 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
-------------------------------------------------

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
is written in reStructuredText, a powerful markup language.

Modify the file as follows:

.. code-block:: rest

   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!

Exporting your documentation to other formats
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Sphinx supports a variety of formats apart from HTML, including PDF, EPUB,
:ref:`and more <builders>`.  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 <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!

.. 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.

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 <built-in-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

   # 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 <builtin-themes>`, and there are also third-party ones.

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`` 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

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 <rst-sections>` 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 <https://pygments.org/docs/lexers/>`_ 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 <rst-directives>` 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.

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 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 <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. 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>`.