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

.. toctree::
   :hidden:

   autoindex
   function
   struct
   class
   enum
   typedef
   define
   variable
   file

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 Directive
~~~~~~~~~~~~~~~~~~~~~~

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 Directive
~~~~~~~~~~~~~~~~~~~~~~~~~~

This directive performs a similar role to the ``doxygenindex`` directive except
that it handles the doxygen xml generation for you. As a result you need to
provide the paths to the files that you would like to be processed. The final
generated output will contain all the content from those files.

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

::

   .. autodoxygenindex:: <filename> [<filename> [...]]
      :source: ...
      :source-path: ...
      :outline:
      :no-link:

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

doxygenfunction Directive
~~~~~~~~~~~~~~~~~~~~~~~~~

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 Directive
~~~~~~~~~~~~~~~~~~~~~~~

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 Directive
~~~~~~~~~~~~~~~~~~~~~~~

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 Directive
~~~~~~~~~~~~~~~~~~~~~~~~

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.

doxygendefine Directive
~~~~~~~~~~~~~~~~~~~~~~~

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 Directive
~~~~~~~~~~~~~~~~~~~~~~~~~

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 Directive
~~~~~~~~~~~~~~~~~~~~~~

This directive generates the appropriate output for a single class. It takes the
standard ``project``, ``path``, ``outline`` and ``no-link`` options and
additonally ``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 behaviour of adding the public members can be customised using
   the ``sections`` option.

``sections``
   Designed to specialise the default behaviour 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 Directive
~~~~~~~~~~~~~~~~~~~~~

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.

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 the root
   paths of the source code for those projects that you would like to be
   automatically processed with doxygen. This saves repetition of long paths
   when using the ``autodoxygenindex`` directive. 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"
         }

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

      .. autodoxygenindex:: file.c subfolder/otherfile.c
         :source: myprojectsource

.. 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 mimise conflicts.

