Add ``basf2`` Variables Documentation to Sphinx
-----------------------------------------------

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

.. rst:directive:: 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.


  .. rst:role:: group

     If present show only the variables in the named group

  .. rst:role:: variables

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

     .. code-block:: rst

        .. 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
:ref:`multiline_cpp_strings`) 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
   :ref:`googlestyle`

.. 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])``).

.. _reStructuredText: http://www.sphinx-doc.org/en/stable/rest.html