Sphinx

# Narrative documentation in Sphinx

## Structuring your documentation across multiple pages

The file `index.rst` created by `sphinx-quickstart` is the 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:

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

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` directive at the end of `index.rst` including the document you just created, as follows:

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:

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

docs/source/index.rst

    Check out the :doc:`usage` section for further information.

The `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 `ref` role, and add an explicit label that acts as a target.

For example, to reference the “Installation” subsection, add a label right before the heading, as follows:

docs/source/usage.rst

    Usage
    =====

    .. _installation:

    Installation
    ------------

    ...

And make the sentence you added in `index.rst` look like this:

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.

What about documenting code objects in Sphinx? Read on!