Directives & Config Variables ============================= .. toctree:: :hidden: autoindex function struct class namespace concept enum enumvalue typedef union define variable file group autofile page .. 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 ` config value to be set. .. _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 the ``members``, ``protected-members``, ``private-members``, ``undoc-members``, ``membergroups`` and ``members-only`` options:: .. doxygenclass:: :project: ... :path: ... :members: [...] :protected-members: :private-members: :undoc-members: :membergroups: ... :members-only: :outline: :no-link: :allow-dot-graphs: Checkout the :ref:`doxygenclass documentation ` for more details and to see it in action. .. _doxygendefine: doxygendefine ~~~~~~~~~~~~~ This directive generates the appropriate output for a single preprocessor define. It behaves the same as the doxygenstruct directive. :: .. doxygendefine:: :project: ... :path: ... :outline: :no-link: Checkout the :ref:`example ` to see it in action. .. _doxygenconcept: doxygenconcept ~~~~~~~~~~~~~~ This directive generates the appropriate output for a single concept. It behaves the same as the doxygenstruct directive. :: .. doxygenconcept:: :project: ... :path: ... :outline: :no-link: Checkout the :ref:`example ` to see it in action. .. _doxygenenum: doxygenenum ~~~~~~~~~~~ This directive generates the appropriate output for a single enum. It behaves the same as the doxygenstruct directive. :: .. doxygenenum:: :project: ... :path: ... :outline: :no-link: Checkout the :ref:`example ` to see it in action. .. _doxygenenumvalue: doxygenenumvalue ~~~~~~~~~~~~~~~~ This directive generates the appropriate output for a single enum value. :: .. doxygenenumvalue:: :project: ... :path: ... :outline: :no-link: Checkout the :ref:`example ` to see it in action. .. _doxygenfile: doxygenfile ~~~~~~~~~~~ This directive generates the appropriate output for the contents of a source file. :: .. doxygenfile:: :project: ... :path: ... :outline: :no-link: :sections: ... :allow-dot-graphs: Checkout the :ref:`example ` to see it in action. .. _autodoxygenfile: 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:: :project: ... :outline: :no-link: :sections: ... :allow-dot-graphs: Checkout the :ref:`example ` to see it in action. .. _doxygenfunction: doxygenfunction ~~~~~~~~~~~~~~~ This directive generates the appropriate output for a single function. The function name is required to be unique in the project. :: .. doxygenfunction:: :project: ... :path: ... :outline: :no-link: Checkout the :ref:`example ` to see it in action. .. _doxygengroup: 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:: :project: ... :path: ... :content-only: :desc-only: :outline: :members: :protected-members: :private-members: :undoc-members: :no-link: :inner: Checkout the :ref:`doxygengroup documentation ` for more details and to see it in action. .. _doxygen grouping documentation: https://www.doxygen.nl/manual/grouping.html .. _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: :allow-dot-graphs: .. _autodoxygenindex: 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: :allow-dot-graphs: Checkout the :ref:`example ` to see it in action. .. _doxygennamespace: 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:: :project: ... :path: ... :content-only: :desc-only: :outline: :members: :protected-members: :private-members: :undoc-members: :no-link: Checkout the :ref:`doxygennamespace documentation ` for more details and to see it in action. .. _doxygenstruct: 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:: :project: ... :path: ... :members: :protected-members: :private-members: :undoc-members: :membergroups: ... :members-only: :outline: :no-link: :allow-dot-graphs: Checkout the :ref:`example ` to see it in action. .. _doxygeninterface: doxygeninterface ~~~~~~~~~~~~~~~~ This directive generates the appropriate output for a single interface (specially-used class). It behaves the same as the doxygenclass directive. :: .. doxygeninterface:: :project: ... :path: ... :members: :protected-members: :private-members: :undoc-members: :membergroups: ... :members-only: :outline: :no-link: .. _doxygentypedef: doxygentypedef ~~~~~~~~~~~~~~ This directive generates the appropriate output for a single typedef. It behaves the same as the doxygenstruct directive. :: .. doxygentypedef:: :project: ... :path: ... :outline: :no-link: Checkout the :ref:`example ` to see it in action. .. _doxygenunion: doxygenunion ~~~~~~~~~~~~ This directive generates the appropriate output for a single union. It behaves the same as the doxygenstruct directive. :: .. doxygenunion:: :project: ... :path: ... :outline: :no-link: Checkout the :ref:`example ` to see it in action. .. _doxygenvariable: doxygenvariable ~~~~~~~~~~~~~~~ This directive generates the appropriate output for a single variable. It behaves the same as the doxygenstruct directive. :: .. doxygenvariable:: :project: ... :path: ... :outline: :no-link: Checkout the :ref:`example ` to see it in action. .. _doxygenpage: 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:: :project: ... :path: ... :content-only: Checkout the :ref:`doxygenpage documentation ` for more details and to see it in action. .. _doxygen xrefitem documentation: https://www.doxygen.nl/manual/commands.html#cmdxrefitem 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", } You can also use this to enable support for Doxygen XML generated from PHP code:: breathe_domain_by_extension = { "php" : "php", } .. 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 :project: 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/`` to the path to minimize conflicts. .. _breathe-default-members: .. confval:: 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: .. confval:: 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: .. confval:: 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. .. confval:: 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{}``) .. confval:: 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``. .. confval:: 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``. .. confval:: 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 Description of Foo. but when set to ``False`` it is instead rendered as:: struct Foo Description of Foo. .. confval:: 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. .. confval:: 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. .. confval:: 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.