Add basf2 Modules Documentation to Sphinx
27.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 inanalysis/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 theframework
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.