28.6. Add basf2 Modules Documentation to Sphinx

basf2 Module documentation can be added to sphinx automatically using

.. b2-modules::

Will automatically document basf2 modules. Without any arguments it will document all existing modules. It has the following optional parameters

:package:

Only document modules found from a specific package

:library:

Only document modules found in the specified library. This is the name of the directory inside the modules/ directory but with a prefix “lib” and suffix “.so”. So if you want to document all modules in analysis/modules/ParticleCombiner this could be

.. b2-modules::
   :library: libParticleCombiner.so

:modules:

Explicitly choose the modules to document with a comma separated list of modules:

.. b2-modules::
   :modules: EventInfoSetter, EventInfoGetter

:regex-filter:

Can be used to filter the modules to be documented by a python regular expression For example to show all modules in the framework package which begin with ‘Event’.

.. b2-modules::
   :package: framework
   :regex-filter: ^Event

Note

Can be used also for variables (see next section). For example to show all variables in the group “Kinematics” which begin with x

.. b2-variables::
   :group: Kinematics
   :regex-filter: ^x.*

:no-parameters:

if present do not document module parameters

:io-plots:

if present it will try to include a graph showing the required, optional and registered DataStore elements.

:noindex:

if present the modules will not be added to the index. This is useful if the same module is documented multiple times to select which of these should show up in the index.

Note

This can be used also with variables (see next section) in that case if present the variables will not be added to the index. This is useful if the same variable is documented multiple times to select which of these should show up in the index.

For this automatic documentation to work all documentation strings passed to setDescription() and addParam() should be valid reStructuredText (see Documentation of Variables and Modules in C++). It is also possible to reference modules elsewhere in the text, for example :b2:mod:`EventInfoSetter`. In most case it will work even when omitting the :b2:mod: but it is recommended to add it to make sure it actually links to the correct thing and not a python function with the same name.