Directives & Config Variables¶
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. Usesource
instead to specify the entry in thebreathe_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. Usesource-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:
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.
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: ...
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: ...
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
, members
, protected-members
,
private-members
and undoc-members
options.
.. doxygengroup:: <group name>
:project: ...
:path: ...
:content-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:
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_config_aliases
will be added to the doxygen aliases.
Thank you to Scopatz for the idea and initial implementation.
.. autodoxygenindex::
:project: ...
:outline:
:no-link:
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
, 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:
: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:
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 thebreathe_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 rundoxygen
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 thedoctrees
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 unnamespaced 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 dictionnary 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 toTrue
, and without if it is set toFalse
.
- 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 toTrue
, and without if it is set toFalse
.
- 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) astruct 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.