Directives & Config Variables
=============================

.. toctree::
   :hidden:

   autoindex
   function
   struct
   class
   namespace
   concept
   enum
   enumvalue
   typedef
   union
   define
   variable
   file
   group
   autofile
   page


Directives
----------

The available directives are shown below. In each case the ``project``,
``path``, ``no-link`` and ``outline`` options have the following meaning:

``project``
   Specifies which project, as defined in the ``breathe_projects`` config value,
   should be used for this directive. This overrides the default project if one
   has been specified.

   This is not used by the `autodoxygenindex`_ directive. Use ``source``
   instead to specify the entry in the :confval:`breathe_projects_source` config value
   to use.

``path``
   Directly specifies the path to the folder with the doxygen output. This
   overrides the project and default project if they have been specified.

   This is not used by the `autodoxygenindex`_ directive. Use ``source-path``
   instead to specify the root path to the sources files which are to be
   processed.

``no-link``
   Instructs Breathe to not attempt to generate any document targets for the
   content generated by this particular directive.

   This allows you to have your main reference listings somewhere with
   targets, but then to be able to sneak in repeat directives into other
   parts of the documentation to illustrate particular points without
   Sphinx getting confused what should be linked to by other references.

``outline``
   Results in Breathe only outputting the raw code definitions without
   any additional description information.

If neither project nor path are provided on the directive then breathe will
expect the :ref:`breathe_default_project <default_project>` config value to be
set.


.. _doxygenclass:

doxygenclass
~~~~~~~~~~~~

This directive generates the appropriate output for a single class. It takes the
standard ``project``, ``path``, ``outline`` and ``no-link`` options and
additionally the ``members``, ``protected-members``, ``private-members``,
``undoc-members``, ``membergroups`` and ``members-only`` options

.. code-block:: rst

   .. doxygenclass:: <class name>
      :project: ...
      :path: ...
      :members: [...]
      :protected-members:
      :private-members:
      :undoc-members:
      :membergroups: ...
      :members-only:
      :outline:
      :no-link:
      :allow-dot-graphs:

Checkout the :ref:`doxygenclass documentation <class-example>` for more details
and to see it in action.

.. _doxygendefine:

doxygendefine
~~~~~~~~~~~~~

This directive generates the appropriate output for a single preprocessor
define. It behaves the same as the `doxygenstruct`_ directive.

.. code-block:: rst

   .. doxygendefine:: <define name>
      :project: ...
      :path: ...
      :outline:
      :no-link:

Checkout the :ref:`example <define-example>` to see it in action.

.. _doxygenconcept:

doxygenconcept
~~~~~~~~~~~~~~

This directive generates the appropriate output for a single concept. It
behaves the same as the `doxygenstruct`_ directive.

.. code-block:: rst

   .. doxygenconcept:: <concept name>
      :project: ...
      :path: ...
      :outline:
      :no-link:

Checkout the :ref:`example <concept-example>` to see it in action.

.. _doxygenenum:

doxygenenum
~~~~~~~~~~~

This directive generates the appropriate output for a single enum. It behaves
the same as the `doxygenstruct`_ directive.

.. code-block:: rst

   .. doxygenenum:: <enum name>
      :project: ...
      :path: ...
      :outline:
      :no-link:

Checkout the :ref:`example <enum-example>` to see it in action.

.. _doxygenenumvalue:

doxygenenumvalue
~~~~~~~~~~~~~~~~

This directive generates the appropriate output for a single enum value.

.. code-block:: rst

   .. doxygenenumvalue:: <enum value name>
      :project: ...
      :path: ...
      :outline:
      :no-link:

Checkout the :ref:`example <enumvalue-example>` to see it in action.

.. _doxygenfile:

doxygenfile
~~~~~~~~~~~

This directive generates the appropriate output for the contents of a source
file.

.. code-block:: rst

   .. doxygenfile:: <filename>
      :project: ...
      :path: ...
      :outline:
      :no-link:
      :sections: ...
      :allow-dot-graphs:

Checkout the :ref:`example <file-example>` to see it in action.

.. _autodoxygenfile:

autodoxygenfile
~~~~~~~~~~~~~~~

This directive is this ``auto`` version of the `doxygenfile`_ directive above.
It handles the doxygen xml generation for you like the other auto directives.

.. code-block:: rst

   .. autodoxygenfile:: <filename>
      :project: ...
      :outline:
      :no-link:
      :sections: ...
      :allow-dot-graphs:

Checkout the :ref:`example <autodoxygenfile-example>` to see it in action.

.. _doxygenfunction:

doxygenfunction
~~~~~~~~~~~~~~~

This directive generates the appropriate output for a single function. The
function name is required to be unique in the project.

.. code-block:: rst

   .. doxygenfunction:: <function name>
      :project: ...
      :path: ...
      :outline:
      :no-link:

Checkout the :ref:`example <function-example>` to see it in action.

.. _doxygengroup:

doxygengroup
~~~~~~~~~~~~

This directive generates the appropriate output for the contents of a doxygen
group. A doxygen group can be declared with specific doxygen markup in the
source comments as covered in the `doxygen grouping documentation`_.

It takes the standard ``project``, ``path``, ``outline`` and ``no-link`` options
and additionally the ``content-only``, ``desc-only``, ``members``,
``protected-members``, ``private-members`` and ``undoc-members`` options.

.. code-block:: rst

   .. doxygengroup:: <group name>
      :project: ...
      :path: ...
      :content-only:
      :desc-only:
      :outline:
      :members:
      :protected-members:
      :private-members:
      :undoc-members:
      :no-link:
      :inner:

Checkout the :ref:`doxygengroup documentation <group-example>` for more details
and to see it in action.

.. _doxygen grouping documentation: https://www.doxygen.nl/manual/grouping.html


.. _doxygenindex:

doxygenindex
~~~~~~~~~~~~

This directive processes and produces output for everything described by the
Doxygen xml output. It reads the ``index.xml`` file and process everything
referenced by it.

.. code-block:: rst

   .. doxygenindex::
      :project: ...
      :path: ...
      :outline:
      :no-link:
      :allow-dot-graphs:

.. _autodoxygenindex:

autodoxygenindex
~~~~~~~~~~~~~~~~

This directive performs a similar role to the `doxygenindex`_ directive except
that it handles the doxygen xml generation for you. It uses the
:confval:`breathe_projects_source` configuration dictionary to judge which code source
files should have doxygen xml generated for them. The ``project`` directive
option associates the directive with a particular project in the
:confval:`breathe_projects_source` dictionary. All the files references by the entry in
the :confval:`breathe_projects_source` will be included in the output. In addition, any
options specified in :confval:`breathe_doxygen_config_options` will be added to the
generated Doxygen config file and any custom aliases specified in
:confval:`breathe_doxygen_aliases` will be added to the `doxygen aliases
<https://www.doxygen.nl/manual/custcmd.html>`_.

Thank you to `Scopatz <https://github.com/scopatz>`_ for the idea and initial
implementation.

.. code-block:: rst

   .. autodoxygenindex::
      :project: ...
      :outline:
      :no-link:
      :allow-dot-graphs:

Checkout the :ref:`example <autodoxygenindex-example>` to see it in action.

.. _doxygennamespace:

doxygennamespace
~~~~~~~~~~~~~~~~

This directive generates the appropriate output for the contents of a namespace.

It takes the standard ``project``, ``path``, ``outline`` and ``no-link`` options
and additionally the ``content-only``, ``desc-only``, ``members``,
``protected-members``, ``private-members`` and ``undoc-members`` options.

To reference a nested namespace, the full namespaced path must be provided, e.g.
``foo::bar`` for the ``bar`` namespace inside the ``foo`` namespace.

.. code-block:: rst

   .. doxygennamespace:: <namespace>
      :project: ...
      :path: ...
      :content-only:
      :desc-only:
      :outline:
      :members:
      :protected-members:
      :private-members:
      :undoc-members:
      :no-link:

Checkout the :ref:`doxygennamespace documentation <namespace-example>` for more
details and to see it in action.

.. _doxygenstruct:

doxygenstruct
~~~~~~~~~~~~~

This directive generates the appropriate output for a single struct. The struct
name is required to be unique in the project.

It takes the standard ``project``, ``path``, ``outline`` and ``no-link`` options
and additionally the ``members``, ``protected-members``, ``private-members``,
``membergroups``, ``members-only`` and ``undoc-members`` options.

.. code-block:: rst

   .. doxygenstruct:: <struct name>
      :project: ...
      :path: ...
      :members:
      :protected-members:
      :private-members:
      :undoc-members:
      :membergroups: ...
      :members-only:
      :outline:
      :no-link:
      :allow-dot-graphs:

Checkout the :ref:`example <struct-example>` to see it in action.

.. _doxygeninterface:

doxygeninterface
~~~~~~~~~~~~~~~~

This directive generates the appropriate output for a single interface (specially-used
class). It behaves the same as the `doxygenclass`_ directive.

.. code-block:: rst

   .. doxygeninterface:: <interface name>
      :project: ...
      :path: ...
      :members:
      :protected-members:
      :private-members:
      :undoc-members:
      :membergroups: ...
      :members-only:
      :outline:
      :no-link:

.. _doxygentypedef:

doxygentypedef
~~~~~~~~~~~~~~

This directive generates the appropriate output for a single typedef. It behaves
the same as the doxygenstruct directive.

.. code-block:: rst

   .. doxygentypedef:: <typedef name>
      :project: ...
      :path: ...
      :outline:
      :no-link:

Checkout the :ref:`example <typedef-example>` to see it in action.

.. _doxygenunion:

doxygenunion
~~~~~~~~~~~~

This directive generates the appropriate output for a single union. It behaves
the same as the doxygenstruct directive.

.. code-block:: rst

   .. doxygenunion:: <union name>
      :project: ...
      :path: ...
      :outline:
      :no-link:

Checkout the :ref:`example <union-example>` to see it in action.

.. _doxygenvariable:

doxygenvariable
~~~~~~~~~~~~~~~

This directive generates the appropriate output for a single variable.
It behaves the same as the doxygenstruct directive.

.. code-block:: rst

   .. doxygenvariable:: <variable name>
      :project: ...
      :path: ...
      :outline:
      :no-link:

Checkout the :ref:`example <variable-example>` to see it in action.

.. _doxygenpage:

doxygenpage
~~~~~~~~~~~

This directive generates the appropriate output for the contents of a doxygen
page. A doxygen page is created for each "key" of every \\xrefitem command used
for markup in the source comments. For more information check the
`doxygen xrefitem documentation`_.

It takes the standard ``project`` and ``path`` options and additionally the
``content-only`` option.

.. code-block:: rst

   .. doxygenpage:: <page name>
      :project: ...
      :path: ...
      :content-only:

Checkout the :ref:`doxygenpage documentation <page-example>` for more details
and to see it in action.

.. _doxygen xrefitem documentation: https://www.doxygen.nl/manual/commands.html#cmdxrefitem



Config Values
-------------

.. confval:: breathe_projects

   This should be a dictionary in which the keys are project names and the values are
   paths to the folder containing the doxygen output for that project.

.. _default_project:

.. confval:: breathe_default_project

   This should match one of the keys in the :confval:`breathe_projects` dictionary and
   indicates which project should be used when the project is not specified on
   the directive.

.. confval:: breathe_domain_by_extension

   Allows you to specify domains for particular files according to their
   extension.

   For example:

   .. code-block:: python

      breathe_domain_by_extension = {
          "h" : "cpp",
      }

   You can also use this to enable support for Doxygen XML generated from PHP code:

   .. code-block:: python

      breathe_domain_by_extension = {
          "php" : "php",
      }

.. confval:: breathe_domain_by_file_pattern

   Allows you to specify domains for particular files by wildcard syntax. This
   is checked after :confval:`breathe_domain_by_extension` and so will override
   it when necessary.

   For example:

   .. code-block:: python

      breathe_domain_by_file_pattern = {
          "\*/alias.h" : "c",
      }

   If you wanted all ``.h`` header files to be treated as being in the **cpp**
   domain you might use the :confval:`breathe_domain_by_extension` example
   above. But if you had one ``.h`` file that should be treated as being in the
   **c** domain then you can override as above.


.. confval:: breathe_projects_source

   A dictionary in which the keys are project names and the values are a tuple
   of the directory and a list of file names of the source code for those
   projects that you would like to be automatically processed with doxygen.
   If you have some files in:
   
   .. code-block:: text

      /some/long/path/to/myproject/file.c
      /some/long/path/to/myproject/subfolder/otherfile.c

   Then you can set:

   .. code-block:: python

      breathe_projects_source = {
          "myprojectsource" : (
              "/some/long/path/to/myproject", ["file.c", "subfolder/otherfile.c"]
          )
      }

   Then your `autodoxygenfile`_ usage can look like this:

   .. code-block:: rst

      .. autodoxygenfile:: file.c
         :project: myprojectsource

   The directory entry in the tuple can be an empty string if the entries in the
   list are full paths.

.. confval:: breathe_build_directory

   In order to process the `autodoxygenindex`_ Breathe has to run ``doxygen``
   to create the xml files for processing. This config value specifies the root
   directory that these files should be created in. By default, this is set to
   the parent directory of the ``doctrees`` output folder which is the normal
   build directory. You can change it with this setting if you have a custom
   set up.

   Breathe will take the final value and append ``breathe/doxygen/<project
   name>`` to the path to minimize conflicts.

.. _breathe-default-members:

.. confval:: breathe_default_members

   Provides the directive flags that should be applied to all directives which
   take ``:members:``, ``:private-members:`` and ``:undoc-members:`` options.
   By default, this is set to an empty list, which means no members are
   displayed. If you'd like to always display the public and public,
   undocumented members then you could set it like this:

   .. code-block:: python

      breathe_default_members = ('members', 'undoc-members')

.. _breathe-implementation-filename-extensions:

.. confval:: breathe_implementation_filename_extensions

   Provides a list of the filename extensions which are considered to be
   implementation files. These files are ignored when the `doxygenfunction`_
   directive looks for un-namespaced function names. This is to avoid the issue
   where the same function name appears in the doxygen XML output for a header
   file and implementation file because the declaration is in one and the
   definition is in the other. Doxygen appends the documentation from the
   definition to the XML for the declaration so we don't miss any documentation
   information from the implementation files. The default value for this
   variable is:

   .. code-block:: python

      breathe_implementation_filename_extensions = ['.c', '.cc', '.cpp']

.. _breathe-doxygen-config-options:

.. confval:: breathe_doxygen_config_options

   A dictionary in which the keys and values are the names and values of config
   options to be placed in the Doxygen config file generated by
   `autodoxygenindex`_. For instance, this:

   .. code-block:: python

      breathe_doxygen_config_options = {'EXCLUDE_SYMBOLS': 'abc123'}

   would place ``EXCLUDE_SYMBOLS=abc123`` in the config file. The default value is
   the empty dictionary.

.. confval:: breathe_doxygen_aliases

   A dictionary in which the keys and values are the names and values of aliases
   to be placed in the Doxygen config file generated by `autodoxygenindex`_.
   For instance, this:

   .. code-block:: python

      breathe_doxygen_aliases = {
          'rstref{1}': r'\verbatim embed:rst:inline :ref:`\1` \endverbatim'
      }

   would place the line::

      ALIASES += rstref{1}="\verbatim embed:rst:inline :ref:`\1` \endverbatim"

   in the config file. The default value is an empty dictionary.
   Note the use of a raw string to ensure that backslashes are interpreted as literal characters.
   (This example alias enables linking to rst targets inline in doxygen comments using
   ``\rstref{<target_name>}``)

.. confval:: breathe_show_define_initializer

   A boolean flag which can be set to ``True`` to display the initializer of a define in the output.

   For example a define ``MAX_LENGTH 100`` would be shown with the value 100 if this is set to ``True``,
   and without if it is set to ``False``.

.. confval:: breathe_show_enumvalue_initializer

   A boolean flag which can be set to ``True`` to display the initializer of an enum value in the output.

   For example an enum value ``TWO = 2`` would be shown with the value 2 if this is set to ``True``,
   and without if it is set to ``False``.

.. confval:: breathe_show_include

   A boolean flag which can be set to ``False`` to hide the header in which each
   entity (struct, function, macro, etc.) is defined.

   For example, when set to ``True`` (the default) a ``struct Foo`` is rendered
   similarly to::

     struct Foo
       #include <foo.hpp>
       Description of Foo.

   but when set to ``False`` it is instead rendered as::

     struct Foo
       Description of Foo.

.. confval:: breathe_use_project_refids

   True or False setting to control if the refids generated by breathe for doxygen
   elements contain the project name or not. Legacy (breathe 4.6.0 and earlier)
   behavior was that all refids are prefixed with the project name. This causes
   trouble when trying to link documentation between multiple projects since the
   projects can't see each other's documentation elements. The new default behavior
   is to not prefix the refids with the project name. This::

      breathe_use_project_refids = True

   will restore the legacy behavior if it is needed.

.. confval:: breathe_order_parameters_first

   True or False setting to control if the parameters section from doxygen generated
   documentation should be placed immediately after the brief and detailed description
   or at the end, after the returns, remarks and warnings section. Default value and
   also the legacy behavior is False.

.. confval:: breathe_separate_member_pages

   True or False setting to control if the input XML generated by Doxygen had the
   Doxygen SEPARATE_MEMBER_PAGES option set to YES or NO. The Doxygen option defaults
   to NO which generates XML that allows Breathe to resolve all references. When set
   to YES the refid/id of elements get an extra element which Breathe tries to get rid
   of when this setting is True.
