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

.. toctree::
   :hidden:

   autoindex
   function
   struct
   class
   enum
   typedef
   union
   define
   variable
   file
   group
   autofile

.. contents:: Table of Contents

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

.. _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.

::

   .. doxygenindex::
      :project: ...
      :path: ...
      :outline:
      :no-link:

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

This directive performs a similar role to the ``doxygenindex`` directive except
that it handles the doxygen xml generation for you. It uses the
``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
``breathe_projects_source`` dictionary. All the files references by the entry in
the ``breathe_projects_source`` will be included in the output.

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

::

   .. autodoxygenindex::
      :project: ...
      :outline:
      :no-link:

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

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

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

::

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

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

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

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

::

   .. doxygenstruct:: <struct name>
      :project: ...
      :path: ...
      :outline:
      :no-link:

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

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

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

::

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

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

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

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

::

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

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

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

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

::

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

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

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

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

::

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

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

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

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

::

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

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

.. _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 ``members`` and ``sections`` option.

``members``
   Designed to behavior in a similar manner to the ``members`` option for the
   ``autoclass`` directive that comes with the Sphinx ``autodoc`` extension.

   If you do not specify this option you will not get any information about the
   class members, just the general class documentation. If you provide it
   without arguments, then Breathe adds all the public members and their
   documentation.  If you specify it with **comma separated** arguments, then
   Breathe will treat the arguments as names of members and provide
   documentation for only those members that have been named.

   The default behavior of adding the public members can be customized using
   the ``sections`` option.

``sections``
   Designed to specialize the default behavior of the ``members`` option.  You
   can specify a comma-separated list of sections to be included if no specific
   members are named.  The list can accept wildcards.  For instance, if you want
   to display the all protected and public members, functions, etc, then specify
   ``:sections: public*, protected*``.
   
   By default, breathe specifies ``public*``.

   Note that if your Doxygen project uses properties, these are excluded by
   default.  Specify ``:sections: public*, property`` to include both public
   members and properties. (The section names correspond to the values of the
   ``kind`` attribute of the Doxygen XML ``sectiondef`` elements.)

::

   .. doxygenclass:: <class name>
      :project: ...
      :path: ...
      :members: [...]
      :sections: [...]
      :outline:
      :no-link:

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

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

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

::

   .. doxygenfile:: <filename>
      :project: ...
      :path: ...
      :no-link:

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

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.

::

   .. autodoxygenfile:: <filename>
      :project: ...
      :outline:
      :no-link:

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

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 cover in the `doxygen documentation`_.

It takes the standard ``project``, ``path``, ``outline`` and ``no-link`` options
and additionally the ``content-only`` option.

``content-only``
   If this flag is specified, then the directive does not output the name of the
   group or the group description and instead outputs the contents of the group.
   This can be useful if the groups are only used for organizational purposes
   and not to provide additional information.

::

   .. doxygengroup:: <group name>
      :project: ...
      :path: ...
      :content-only:
      :no-link:

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

.. _doxygen documentation: http://www.stack.nl/~dimitri/doxygen/manual/grouping.html


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::

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

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

      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::

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

   Then you can set::

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

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

      .. autodoxygenfile:: file.c
         :source: 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.

