Writing and building documention for Siconos Software¶

Documentation overview¶

The whole Siconos documentation is gathered on Siconos webpage, https://nonsmooth.gricad-pages.univ-grenoble-alpes.fr/siconos/. It consists in

Different “textbooks” : details on algorithms, how to install, use the platform, … everything user and developers should know concerning Siconos software.
- Getting and installing Siconos software
- Users’ guide
- Developers’ guide
All these guides are generated with sphinx (http://www.sphinx-doc.org/en/master/index.html) from files written in reStructuredText (http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)

Source files and sphinx configuration file are all in docs/sphinx directory.
Siconos APIs (Python and C++) documentation, automatically generated from inline comments in source files ( .h and .hpp).

Rules and best practices to write comments leading to a proper html documentation are detailed in Document source code.
In addition to these pages, “inline” documentation for the python API, as usual for python packages, based on docstrings, e.g. :
```
>>> import siconos.modeling as sm
>>> help(sm.LagrangianDS)
Help on ...
 ...
```

The complete documentation can be generated in one shot using doc target

cd build-dir
cmake -DWITH_DOCUMENTATION=ON path_to_siconos_sources
make
make doc

It results in html pages, generated in build-dir/docs/build/html. Siconos web site (http://siconos.org) is the online version of those pages.

The building process for documentation is described in Building process.

How to write Siconos documentation¶

Writing textbooks¶

Textbooks are generated from rst files from source-dir/docs/sphinx directory.
Everything you need to know to write siconos docs in reStructuredTextPrimer is available here : http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html.
All rst files are copied from source dir to binary dir by cmake, so edit only files in source dir.
All figures and images must be in sphinx/figures directory.

Document source code¶

Since source code comments (in c/c++ header files) are used to generate doxygen, sphinx and docstrings documentation, one has to be very careful when writing those comments and follow the rules below.

General rules

Document all header files using doxygen comments, as defined in http://www.stack.nl/~dimitri/doxygen/manual/index.html
Try to follow numpydoc (https://numpydoc.readthedocs.io/en/latest/) requirements.

files description

Each header file must contain something like

/*! @file SimpleMatrix.hpp
  Brief (no more than one line) description of the content of the file
*/

The name and description will be used in the API contents listings. If this block is not present, the file (and all the objects or functions it contents) won’t appear in the documentation.

Classes and structs

Document each class like this

/**
   @brief Short description of the class

   Detailed description
   equations (see details about latex below), reference to textbooks chapter and so on
*/
class SiconosVector
...

Class methods or functions

/** @brief brief description
 *
 *  @param name_of_param1 description of the param
 *  @param name_of_param2 description of the param
 *  @return description of what is returned
*/
double some_function(int p, int v)

No need to repeat parameters types in comments (param or return)! They will be extracted from function prototype. Something like

/** @brief get size of A
*   @param A double A
*   @return unsigned int
*/
unsigned int size(double * A) const;

is totally useless …

Warning

Space, tab and newline are important and taken into account, especially when generating docstrings and doc from docstrings !

always add a newline before the first @param or @return
align properly everything with the first line of the doxygen comment

Correct:

/** @brief brief description
 *
 *  @param name_of_param1 description of the param
 *  @param name_of_param2 description of the param
 *  @return description of what is returned
 */

Wrong (missing newline and wrong indent):

/** @brief brief description
 * @param name_of_param1 description of the param
 * @param name_of_param2 description of the param
 * @return description of what is returned
 */

rst inside doxygen commments

Use “\rst” / “\endrst” tags to write reStructuredText (reST) specific (i.e. that doxygen can not tackle) comments. See details below for references and math formula.

In the case of comments with leading asterisk, use “\rststar” / “\endrststar” tags

Rq: most of the time it breaks the rendering of python API outputs.

Enums, union …

Since they will probably appear as global variables in python API, it’s important that each component of the enum has an explicit comment, e.g:

/** Global description of the enum */
enum UBLAS_TYPE
{
 /** id for dense matrix or vector */
 DENSE = 1,
 /** id for triangular matrix */
 TRIANGULAR,
}

References to sphinx documents¶

To refer to any other sphinx document (reminder about sphinx cross-ref : http://www.sphinx-doc.org/en/stable/markup/inline.html) use “\rst” / “\endrst” tags :

/** Class used to defined friction-contact problems

This class deals with blabla

\rst

 See :ref:`global_fc_problem`

\endrst

*/

or with leading asterisk

/** Class used to defined friction-contact problems
 *
 * This class deals with blabla
 *
 * \rststar
 *
 *   See :ref:`global_fc_problem`
 *
 * \endrststar
 *
 *
 */

Math and latex¶

inline math

use this \f$ \alpha \f$ to write inline math

Important: always put a space after and before \f$

displayed math
- Wrap your formula between “f[t” and “f]” tags and write math as you would with latex.

Building process¶

One target to generate the whole documentation :

cmake -DWITH_DOCUMENTATION=ON ...
make doc # The whole doc

Resulting files will be in docs/build/html of the current building path.

Below are some details about the documentation generation process, useful only if you want to generate a subpart of the doc or change the configuration and the process.

Tools, config and description¶

Tools

Doxygen: used to generate xml files from comments in source code (hpp C/C++ headers)
Breathean extension to reStructuredText and Sphinx to be able to read and render the Doxygen xml outputs.
Used to convert xml outputs of doxygen to rst files.
SphinxApidoc: used to generate rst files from docstrings in Python code (pure or from pybind11)
Sphinx : powerful generator of documentation (mostly for Python). Will generate html outputs from rst files

See the file docs/requirements.txt in siconos repository for a list of required python packages.

Config and sources:

docs/CMakeLists.txt : main driver
cmake/doc_tools.cmake : cmake macros and functions calling doxygen, sphinx or other tool related to documentation.
cmake/doxygen_warning.cmake : included in LibraryProjectSetup, rules to build “*.warnings” files.
docs/sphinx/conf.py.in : main sphinx configuration file
docs/sphinx/index.rst.in : source for documentation main page
docs/sphinx/*/*.rst : inputs for sphinx doc (textbooks)
docs/sphinx/figures/* : all figures used in sphinx doc
docs/gendoctools/* : python tools used to generate docs. This python package will be installed in <CMAKE_BINARY_DIR>/share at build time.

Process

The whole process is executed with “make doc” and is summarized on the figure below.

../_images/build_breathe.png — Generation of the documentation for the C++ and Python API¶

Remark : during generation process, siconos python packages are imported and only objects with non-empty docstrings are documented.

Other (exotic) configuration options

Full doxygen (i.e. extract all from sources!) html documentation.

Target : developpers only. Indeed, everything is included in sphinx doc except things like callgraph or collaboration graphs. Use this when those graphs are needed.

Same as above, with a new cmake option :

cmake -DWITH_DOCUMENTATION=ON -DUSE_DEVEL_DOXYGEN=ON
make doc # The whole doc

Doxygen ouput is set to be “quiet” and without warnings. But, if required (devel), use:

Generate doxygen warnings

Use WITH_DOXYGEN_WARNINGS option (in USER_OPTIONS_FILE or in command line), e.g. :
```
cmake -DWITH_DOCUMENTATION=ON -DWITH_DOXYGEN_WARNINGS=ON
make filter_warnings
```
It will generate (during compilation process) and print doxygen warnings in files saved in CMAKE_BINARY_DIR/doxygen_warnings. A warnings file is generated for each input source file. The final call to ‘make filter_warnings’ will concatenate all interesting warnings into one file, doxygen_warnings/SUMMARY.warnings

doxygen warnings conf is defined in docs/config/doxy_warnings.config.in and setup in cmake/doxygen_warnings.cmake.

python3 -m pip install -rU ./docs/requirements.txt

See also the file ci_gitlab/make_siconos_doc.sh in siconos repository. It may be helpful to install siconos docs, since it is used by continuous integration on gitlab to provide all dependencies required to build doc on ubuntu.