This section deals with the sphinx documentation included in the library repository and built on top the Python interface.
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.
- The numpydoc Sphinx extension is used for a structured semi-automatic generation of the User Manual from the docstrings of OpenTURNS objects.
- 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.
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 (
and are then included in the main SWIG header files
For instance, the docstrings for the
are defined in
Arcsine_doc.i.in, and this docstring file is then
Arcsine.i using a %include Arcsine_doc.i.
Note the difference between the name of the docstring file in the source
Arcsine_doc.i.in) and its reference in
.in suffix disappeared because the docstring files are
preprocessed by CMake in order to escape LaTeX backslashes for SWIG and
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.
Please follow PEP257 and
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. ...).
Using maths is highly recommended for illustrating the mathematical concepts
featured in OpenTURNS. Mathematical expression must use Sphinx
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.
Please use the math commands defined in our
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).
The OpenTURNS library counts an important number of parent objects with an
Implementation pattern. For instance, the
object which is the base class for all probability distributions in OpenTURNS
DistributionImplementation pattern (that we don’t
need to expose). And the trick is that the base object does not inherit from
Implementation pattern but the children do, so we need to
document them both.
In order to avoid docstrings duplicates though we decided to document the
Implementation pattern with defined blocks. Since we load the
Implementation patterns first, we can then refer to the same defined
blocks for documenting the object itself.
For instance the main docstring of the
object is defined and referred to in the
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
SWIG header file:
... %feature("docstring") OT::Distribution OT_Distribution_doc ...
Integration to the building suite¶
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:
- Path to the sphinx-build command.
- 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