Documenting Python objects¶

Sphinx offers several roles and directives to document Python objects, all grouped together in the Python domain. For example, you can use the py:function directive to document a Python function, as follows:

Creating recipes
----------------

To retrieve a list of random ingredients,
you can use the ``lumache.get_random_ingredients()`` function:

.. py:function:: lumache.get_random_ingredients(kind=None)

   Return a list of random ingredients as strings.

   :param kind: Optional "kind" of ingredients.
   :type kind: list[str] or None
   :return: The ingredients list.
   :rtype: list[str]

Which will render like this:

Notice several things:

• Sphinx parsed the argument of the .. py:function directive and highlighted the module, the function name, and the parameters appropriately.

• The directive content includes a one-line description of the function, as well as an info field list containing the function parameter, its expected type, the return value, and the return type.

Cross-referencing Python objects¶

By default, most of these directives generate entities that can be cross-referenced from any part of the documentation by using a corresponding role. For the case of functions, you can use py:func for that, as follows:

The ``kind`` parameter should be either ``"meat"``, ``"fish"``,
or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
will raise an exception.

When generating code documentation, Sphinx will generate a cross-reference automatically just by using the name of the object, without you having to explicitly use a role for that. For example, you can describe the custom exception raised by the function using the py:exception directive:

.. py:exception:: lumache.InvalidKindError

   Raised if the kind is invalid.

Then, add this exception to the original description of the function:

.. py:function:: lumache.get_random_ingredients(kind=None)

   Return a list of random ingredients as strings.

   :param kind: Optional "kind" of ingredients.
   :type kind: list[str] or None
   :raise lumache.InvalidKindError: If the kind is invalid.
   :return: The ingredients list.
   :rtype: list[str]

And finally, this is how the result would look:

Beautiful, isn’t it?

Including doctests in your documentation¶

Since you are now describing code from a Python library, it will become useful to keep both the documentation and the code as synchronized as possible. One of the ways to do that in Sphinx is to include code snippets in the documentation, called doctests, that are executed when the documentation is built.

To demonstrate doctests and other Sphinx features covered in this tutorial, Sphinx will need to be able to import the code. To achieve that, write this at the beginning of conf.py:

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here.
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[2]))

Then, before adding doctests to your documentation, enable the doctest extension in conf.py:

extensions = [
    'sphinx.ext.duration',
    'sphinx.ext.doctest',
]

Next, write a doctest block as follows:

>>> import lumache
>>> lumache.get_random_ingredients()
['shells', 'gorgonzola', 'parsley']

Doctests include the Python instructions to be run preceded by >>>, the standard Python interpreter prompt, as well as the expected output of each instruction. This way, Sphinx can check whether the actual output matches the expected one.

To observe how a doctest failure looks like (rather than a code error as above), let’s write the return value incorrectly first. Therefore, add a function get_random_ingredients like this:

def get_random_ingredients(kind=None):
    return ["eggs", "bacon", "spam"]

You can now run make doctest to execute the doctests of your documentation. Initially this will display an error, since the actual code does not behave as specified:

(.venv) $ make doctest
Running Sphinx v4.2.0
loading pickled environment... done
...
running tests...

Document: usage
---------------
**********************************************************************
File "usage.rst", line 44, in default
Failed example:
    lumache.get_random_ingredients()
Expected:
    ['shells', 'gorgonzola', 'parsley']
Got:
    ['eggs', 'bacon', 'spam']
**********************************************************************
...
make: *** [Makefile:20: doctest] Error 1

As you can see, doctest reports the expected and the actual results, for easy examination. It is now time to fix the function:

def get_random_ingredients(kind=None):
    return ["shells", "gorgonzola", "parsley"]

And finally, make doctest reports success!

For big projects though, this manual approach can become a bit tedious. In the next section, you will see how to automate the process.

Documenting and cross-referencing objects¶

Sphinx also supports documenting and cross-referencing objects written in other programming languages. There are four additional built-in domains: C, C++, JavaScript, and reStructuredText. Third-party extensions may define domains for more languages, such as

• Fortran,

• Julia, or

• PHP.

For example, to document a C++ type definition, you would use the built-in cpp:type directive, as follows:

.. cpp:type:: std::vector<int> CustomList

   A typedef-like declaration of a type.

Which would give the following result:

typedef std::vector<int> CustomList¶

A typedef-like declaration of a type.

All such directives then generate references that can be cross-referenced by using the corresponding role. For example, to reference the previous type definition, you can use the cpp:type role as follows:

Cross reference to :cpp:type:`CustomList`.

Which would produce a hyperlink to the previous definition: CustomList.