Sphinx documentation

This section deals with the sphinx documentation included in the library repository and built on top the Python interface.

Sphinx 101

This documentation is powered by the Sphinx documentation system. Hence, reading Sphinx’s own documentation might be a good idea for starters! You will also need to learn some basics about its main featured language: reStructuredText.

Sphinx extensions

numpydoc

The numpydoc Sphinx extension is used for a structured semi-automatic generation of the User Manual from the docstrings of OpenTURNS objects.

matplotlib.sphinxext.plot_directive

The plot_directive Matplotlib/Sphinx extension is used for executing and testing the code blocks featured in the pages of this documentation, especially in the examples section.

sphinx_gallery.gen_gallery

The gen_gallery extension from Sphinx-Gallery is used to generate pages from the examples directory.

Docstrings (in separate SWIG header files)

OpenTURNS main featured language is C++. We then use SWIG in order to generate the Python interface. Hence, docstrings are defined within dedicated SWIG header files ($OT_SOURCE_DIR/python/src/*_doc.i.in) and are then included in the main SWIG header files ($OT_SOURCE_DIR/python/src/*.i).

For instance, the docstrings for the Arcsine distribution are defined in Arcsine_doc.i.in, and this docstring file is then included in Arcsine.i using a %include Arcsine_doc.i.

Note

Note the difference between the name of the docstring file in the source tree (Arcsine_doc.i.in) and its reference in Arcsine.i. The .in suffix disappeared because the docstring files are preprocessed by CMake in order to escape LaTeX backslashes for SWIG and Python.

Note also that the use of double quotes (”) in docstrings is forbidden. This is because SWIG uses them to delimit the docstrings.

Here are a few recommendations you’d better read in order to help us enhancing the docstrings coverage.

Docstring conventions

Please follow PEP257 and numpydoc guidelines for writing the docstrings as well as PEP8 recommendations for the Examples section (for instance, please don’t from openturns import *, indent with 4 spaces, etc. …).

LaTeX

Using maths is highly recommended for illustrating the mathematical concepts featured in OpenTURNS. Mathematical expression must use Sphinx :math: roles for inline maths, and .. math:: directives for equations. These equations will appear as plain LaTeX at prompt (using the help command in Python or the ? suffix in IPython) but Sphinx will render them as PNG images in the User Manual.

Note

Please use the math commands defined in our math_notations.sty LaTeX package.

Docstrings & inheritance

Good news! Docstrings are inherited so that we only need to document the methods of the parent objects (until we want to make them more specific).

Bridge pattern

An important number of objects use the bridge pattern. For instance, the Distribution object which is the interface class for all probability distributions has an implementation class DistributionImplementation (that we don’t need to expose). And the trick is that the interface class does not inherit from its implementation object but the children do, so we need to document them both.

In order to avoid docstrings duplicates though we decided to document the implementation class with defined blocks. Since we load the implementation first, we can then refer to the same defined blocks for documenting the object itself.

For instance the main docstring of the Distribution object is defined and referred to in the DistributionImplementation_doc.i.in SWIG header file:

...
%define OT_Distribution_doc
"Base class for probability distributions."
%enddef
%feature("docstring") OT::DistributionImplementation
OT_Distribution_doc
...

and it is then only being referred to in the Distribution_doc.i.in SWIG header file:

...
%feature("docstring") OT::Distribution
OT_Distribution_doc
...

Integration to the build system

The separate docstring SWIG header files are included in the SWIG header files of the openturns repos, so this does not need any further integration steps (out of the backslashes escaper CMake script). A docstring test (python/test/t_docstring.py) has been added to the Python tests.

We added the following CMake variables:

SPHINX_EXECUTABLE

Path to the sphinx-build command.

SPHINX_FLAGS

This is passed as the options of the sphinx-build command (see sphinx-build invocation).

All these targets depend on the rst files located in the sources ($OT_SOURCE_DIR/python/doc/*.rst).

Example gallery

Example pages are generated from Python scripts in the examples directory ($OT_SOURCE_DIR/python/doc/examples/*.py).

Each page allows to display notebook-like code or text cells. Each cell is delimited by a specific marker and the text cells are written in rst format, for example:

# %%
# First cell (text) in *rst* format inside comments
# Some formula :math:`\lambda = 4`

# %%
import openturns as ot
print("Second cell (code)")
dist = ot.Normal()

Output cells are rendered at compilation time, so the script must not be too long to run.

Figures are automatically generated from the matplotlib handles, for example using the openturns.viewer module:

# %%
from openturns.viewer import View
graph = dist.drawPDF()
view = View(graph)

Note that sphinx runs the examples in the same Python process so you might want to reset the random generator at the beginning of your example for consistent results:

# %%
import openturns as ot
ot.RandomGenerator.SetSeed(0)

The special variable sphinx_gallery_thumbnail_number can be used to determine which figure is used as thumbnail in the examples gallery:

# %%
# sphinx_gallery_thumbnail_number = 3