Ctrl+K

Writing and building documention for Siconos Software

Writing and building documention for Siconos Software#

Documentation overview#

The whole Siconos documentation is gathered on Siconos webpage, https://siconos.gforge.inria.fr. 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.kernel as sk
>>> help(sk.SimpleMatrix)
Help on class SimpleMatrix in module siconos.kernel:

class SimpleMatrix(SiconosMatrix)
|  Matrix (embedded various types of Boost matrices of double)
|
|  SimpleMatrix is used in the platform to store matrices (mathematical object) of
|  double.
 ...

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 (https://siconos.gforge.inria.fr) 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

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

/**
   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 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

/** 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 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 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 : tool able to generate documentation from annotated C++ sources, in html, xml …

  • Sphinx : powerful generator of documentation (mostly for Python)

  • Breathe : an extension to reStructuredText and Sphinx to be able to read and render the Doxygen xml outputs.

Images are sometimes better than words : the different operations are detailed on figures below

Generation of rst files for C++ API

How does it work?

Doxygen is used to generate xml files from comments in headers of each Siconos component. Python scripts are used to postprocess those xml files and produce rst files fitting with Breathe requirements and ready for Sphinx_.

Config and sources:

  • cmake/doc_tools.cmake : cmake macros and functions calling doxygen, sphinx or other tool related to documentation.

  • docs/gendoctools/* : python tools used to generate docs. This python package will be installed in <CMAKE_BINARY_DIR>/share at build time.

  • docs/config/doxyxml2sphinx.config.in : doxygen (xml output) for breathe/sphinx

../_images/build_breathe.png

Generation of rst files for C++ API#

Generation of rst files for Python API

How does it work?

Doxygen generates xml from comments in headers. Some python scripts are used to postprocess those xml files and produce .i files (swig), ending in docstrings in generated swig python modules.

Update: we now use “-doxygen” option of swig to generate docstrings in python files from c++ doxygen comments. doxy2swig interface is outdated.

Config and sources:

  • cmake/swig_python_tools.cmake : python functions used to drive docstrings generation

  • docs/gendoctools/* : python tools used to generate docs. This python package will be installed in <CMAKE_BINARY_DIR>/share at build time.

../_images/build_doxy2swig.png

Generation of rst files for Python API. Warning: doxy2swig part is outdated and has been replaced by swig -doxygen.#

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

html pages generation

How does it work?

All rst files (from source dir and generated for Python and C++ API) and processed by Sphinx to produce html documentation.

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.

../_images/build_html_process.png

make doc toolchain#

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.

  • Generate docstrings

    cmake -DWITH_DOCUMENTATION=ON -DWITH_DOXY2SWIG=ON
make numerics_docstrings

    This option is set to ON by default.

    To produce documentation in python interface, xml outputs from doxygen are used to create swig files containing ‘docstrings’ for python.

    Comments written in C++ (doxygen) will be available in python interface, e.g. :

    import siconos.kernel as sk
help(sk.DynamicalSystem)

Help on class LCP in module siconos.kernel:

class LCP(LinearOSNS)
|  Non Smooth Problem Formalization and Simulation.
|
|  author: SICONOS Development Team - copyright INRIA
|
|  This is an abstract class, that provides an interface to define a non smooth
|  problem:
|
|  *   a formulation (ie the way the problem is written)
|  *   a solver (algorithm and solving formulation, that can be different from
|      problem formulation)
|  *   routines to compute the problem solution.

Dependencies#

See docs/requirements.txt for a list of required python packages, and try for example

pip install -r ./docs/requirements.txt

See also the file CI/make_siconos_doc.sh that 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.

More about Doxygen to sphinx rst#

Some other tools to generate rst from doxygen have been tested : Exhale and doxyrest. We choose breathe, that seems more appropriate to our case. Exhale and doxyrest configs are kept for the records in siconos-junk/sandbox project.

Existing tools (as far as we know …):

Contents