Directives & Config Variables

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 breathe_default_project config value to be set.

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

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

Checkout the doxygenclass documentation for more details and 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 example to see it in action.

doxygenconcept

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

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

Checkout the 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 example to see it in action.

doxygenenumvalue

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

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

Checkout the example to see it in action.

doxygenfile

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

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

Checkout the 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:
   :sections: ...
   :allow-dot-graphs:

Checkout the 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 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 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.

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

Checkout the doxygengroup documentation for more details and to see it in action.

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:
   :allow-dot-graphs:

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. In addition, any options specified in breathe_doxygen_config_options will be added to the generated Doxygen config file and any custom aliases specified in breathe_doxygen_aliases will be added to the doxygen aliases.

Thank you to Scopatz for the idea and initial implementation.

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

Checkout the example to see it in action.

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.

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

Checkout the doxygennamespace documentation for more details and 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.

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.

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

Checkout the example to see it in action.

doxygeninterface

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

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

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 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 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 example to see it in action.

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.

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

Checkout the doxygenpage documentation for more details and to see it in action.

Config Values

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.

breathe_default_project

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

breathe_domain_by_extension

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

For example:

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

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

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

breathe_domain_by_file_pattern

Allows you to specify domains for particular files by wildcard syntax. This is checked after 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 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.

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

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

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

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:

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

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:

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

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:

breathe_doxygen_config_options = {'EXCLUDE_SYMBOLS': 'abc123'}

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

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:

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>})

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.

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.

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.

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.

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.

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.