Directives & Config Variables ¶

Table of Contents

Directives & Config Variables
- Directives
- Config Values

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.

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 for the idea and initial implementation.

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

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.

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

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.

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.

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.

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 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 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 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 example 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",
        }

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