14.7. Add basf2 Variables Documentation to Sphinx

We can also add documentation for basf2 variables with a very similar syntax to modules:

.. b2-variables::

Allows to automatically document basf2 variables from the VariableManager. It has the following optional parameters.

Note

:regex-filter: and :noindex: can be used also for b2-variables as described in previous section.

:group:

If present show only the variables in the named group

:variables:

Can be used to specify a comma separated list of variable names to show, for example

.. b2-variables::
   :variables: x,y,z

Will only produce documentation for the variables x, y, and z

For this automatic documentation to work all documentation strings passed to REGISTER_VARIABLE() should be valid reStructuredText (see Documentation of Variables and Modules in C++) It is also possible to reference variables elsewhere in the text, for example :b2:var:`pidProbabilityExpert`. In most case it will work even when omitting the :b2:var: 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.

Important

Please document any parameters your variable might have using Google Style Docstrings

Note

The variable signature (the name(...) string passed to REGISTER_VARIABLE()) is used to document the expected arguments. Mark optional arguments with square brackets, e.g. myVariable(required[, optional]). Optional arguments must always come after all required arguments: do not write signatures such as myVariable([optional, ]required). Do not use Python-style keyword/default syntax such as myVariable(required, optional=default): basf2 arguments are always positional and keyword arguments are not supported. Describe the default value of an optional argument in the description text instead. Square brackets are reserved for optional arguments, so do not use them to annotate units (e.g. write myVariable(radius) and state in the description that radius is in cm, not myVariable(radius [cm])).