Documentation

Publication

HTML documentation, if saved in a github repository, can be displayed using a https://htmlpreview.github.io/?https://github.com/... indirection (inspired from https://stackoverflow.com/questions/8446218/how-to-see-an-html-page-on-github-as-a-normal-rendered-html-page-to-see-preview#12233684). The display however is not optimal.

The documentation is published on the https://docs.readthedocs.io/ platform.

Docstrings

Python docstrings follow the ReStructured Text format.

PyCharm configuration

In order to make PyCharm use the ReStructured Text format for docstrings, go through: “File” > “Settings” > “Tools” > “Python Integrated Tools” > “Docstrings” > “Docstring format” (as of PyCharm 2021.1.1)

Select the “reStructured Text” option.

The ‘Initializer’ word in __init__() docstrings should be avoided. __init__() docstrings should be more specific on what the initializers do for the object.

Sphinx accepts a couple of keywords for a same meaning (see stackoverflow.com#34160968 and github.com). Let’s choose of them:

Preferred ReStructured Text tags

Preferred tag	Unused tags	Justification
:return:	:returns:	:return: is the default tag used by PyCharm when generating a docstring pattern.
:raise:	:raises:	Consistency with :return:.

The :raise: syntax is the following:

"""
:raise: Unspecified exception type.
:raise ValueError: System exception.
:raise .neighbourmodule.MyException: Project defined exception.
"""

The exception type can be specified:

• It must be set before the second colon (Sphinx handles it a makes an dedicated presentation for it).

• It can be either a system exception type, or a project exception defined in the current or a neighbour module (same syntax as within a :class:`MyException` syntax).

Admonitions: notes, warnings…

The .. admonition:: directive makes it possible to define a title for a “message box” block (see https://docutils.sourceforge.io/docs/ref/rst/directives.html#generic-admonition). Eg:

.. admonition:: Message box title
    :class: tip

    Message box content...

Message box title

Message box content…

The :class: attribute shall be set with one of the following classes (see https://docutils.sourceforge.io/docs/ref/rst/directives.html#specific-admonitions):

• tip (do not use hint)

• note

• important

• warning (do not use attention, caution nor danger)

• error

When no title is needed, the directive with names corresponding to the selected classes above may be used. Eg:

.. tip:: Short tip text, without title,
         which may be continued on the next line.

Tip

Short tip text, without title, which may be continued on the next line.

ReStructured Text indentation

ReStructured Text directives could lead to use indentations of 3 spaces.

Considering that this is hard to maintain with regular configurations of editors, 4 space indentations shall be preferred in docstrings and .rst files.

Domains

Default domain

Unless the .. default-domain:: directive is used, the Python domain is the default domain.

We do not use the :py domain specification in the Python docstrings, in as much as it is implicit.

However, we use the :py domain specification in .rst files in order to be explicit for cross referencing python objects.

Cross references

Use relative imports as much as possible to reference symbols out of the current module.

In as much as Sphinx does not provide a directive to cross-reference them, use double backquotes to highlight function and method parameters.

Cross referencing parameters

There is no current cross reference directive for function and method parameters (see sphinx#538).

From the documentation of the python domain, the best existing directive would be :obj: but it is not really clear (:attr: is for data attributes of objects).

Other useful resources on that topic:

• https://stackoverflow.com/questions/11168178/how-do-i-reference-a-documented-python-function-parameter-using-sphinx-markup

• https://pypi.org/project/sphinx-paramlinks/

Module attributes

Module attributes should be documented using the .. py:attribute:: pragma, extending the __doc__ variable.

__doc__ += """
.. py:attribute:: MY_CONST

    Attribute description.
"""
MY_CONST = 0  # type: int

Otherwise, they may not be cross-referenced from other modules.

Property return type hint

sphinx.ext.autodoc does not make use of property return type hints in the output documentation.

Nevertheless, we do not make use of the :type: directive, which would be redundant with the return type hint already set. The sphinx#7837 enhancement request has been opened for that purpose.