Sphinx Directives

Breathe provides 17 Sphinx directives for documenting C/C++ code elements from Doxygen XML output. These directives integrate seamlessly with Sphinx's reStructuredText processing and support extensive customization options.

Capabilities

Index and File Directives

Generate comprehensive documentation indexes and document entire files with all their contents.

.. doxygenindex::
   :project: project_name
   :outline:
   :no-link:

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

.. doxygenfile:: filename.h
   :project: project_name
   :sections:
   :no-link:
   :allow-dot-graphs:

.. autodoxygenfile:: filename.h
   :project: project_name
   :sections:
   :no-link:
   :allow-dot-graphs:

doxygenindex: Creates a comprehensive index of all documented elements in the project.

autodoxygenindex: Like doxygenindex but automatically generates Doxygen XML first.

doxygenfile: Documents an entire file including all classes, functions, and variables within it.

autodoxygenfile: Like doxygenfile but automatically generates Doxygen XML first.

Class and Structure Directives

Document object-oriented programming constructs including classes, interfaces, structures, and unions.

.. doxygenclass:: ClassName
   :project: project_name
   :path: xml_path
   :members:
   :membergroups: public,protected
   :members-only:
   :protected-members:
   :private-members:
   :undoc-members:
   :show: section_name
   :outline:
   :no-link:
   :allow-dot-graphs:

.. doxygeninterface:: InterfaceName
   :project: project_name
   :path: xml_path
   :members:
   :membergroups: public,protected
   :members-only:
   :protected-members:
   :private-members:
   :undoc-members:
   :show: section_name
   :outline:
   :no-link:
   :allow-dot-graphs:

.. doxygenstruct:: StructName
   :project: project_name
   :path: xml_path
   :members:
   :membergroups: public,protected
   :members-only:
   :protected-members:
   :private-members:
   :undoc-members:
   :show: section_name
   :outline:
   :no-link:
   :allow-dot-graphs:

.. doxygenunion:: UnionName
   :project: project_name
   :path: xml_path
   :members:
   :membergroups: public,protected
   :members-only:
   :protected-members:
   :private-members:
   :undoc-members:
   :show: section_name
   :outline:
   :no-link:
   :allow-dot-graphs:

doxygenclass: Documents C++ classes with full member documentation.

doxygeninterface: Documents interfaces (primarily for languages like C# and Java).

doxygenstruct: Documents C/C++ structures.

doxygenunion: Documents C/C++ unions.

Function and Variable Directives

Document functions, methods, variables, and preprocessor definitions.

.. doxygenfunction:: functionName
   :project: project_name
   :path: xml_path
   :outline:
   :no-link:

.. doxygenvariable:: variableName
   :project: project_name
   :path: xml_path
   :outline:
   :no-link:

.. doxygendefine:: MACRO_NAME
   :project: project_name
   :path: xml_path
   :outline:
   :no-link:

doxygenfunction: Documents individual functions or methods, including overloaded functions.

doxygenvariable: Documents global variables and member variables.

doxygendefine: Documents preprocessor macros and #define statements.

Type and Concept Directives

Document type definitions, enumerations, and modern C++ concepts.

.. doxygentypedef:: TypedefName
   :project: project_name
   :path: xml_path
   :outline:
   :no-link:

.. doxygenenum:: EnumName
   :project: project_name
   :path: xml_path
   :outline:
   :no-link:

.. doxygenenumvalue:: ENUM_VALUE
   :project: project_name
   :path: xml_path
   :outline:
   :no-link:

.. doxygenconcept:: ConceptName
   :project: project_name
   :path: xml_path
   :outline:
   :no-link:

doxygentypedef: Documents typedef declarations and type aliases.

doxygenenum: Documents enumeration types with their values.

doxygenenumvalue: Documents individual enumeration values.

doxygenconcept: Documents C++20 concepts.

Container Directives

Document logical groupings and organizational structures.

.. doxygennamespace:: NamespaceName
   :project: project_name
   :path: xml_path
   :content-only:
   :outline:
   :no-link:

.. doxygengroup:: GroupName
   :project: project_name
   :path: xml_path
   :content-only:
   :outline:
   :no-link:
   :inner:
   :members:
   :membergroups: public,protected
   :private-members:
   :undoc-members:

.. doxygenpage:: PageName
   :project: project_name
   :path: xml_path
   :content-only:
   :outline:
   :no-link:

doxygennamespace: Documents C++ namespaces and their contents.

doxygengroup: Documents Doxygen groups (logical groupings created with @defgroup).

doxygenpage: Documents Doxygen pages (created with @page commands).

Common Directive Options

Project Selection Options

• :project: - Specify which project to use (from breathe_projects config)
• :path: - Direct path to XML files (alternative to project)

Member Control Options

• :members: - Include member documentation
• :membergroups: - Specify which member groups to include (public, protected, private)
• :members-only: - Show only members, not the container description
• :protected-members: - Include protected members
• :private-members: - Include private members
• :undoc-members: - Include undocumented members

Display Options

• :outline: - Show only declarations without detailed descriptions
• :no-link: - Don't create cross-reference links
• :content-only: - Show only content, not the container
• :sections: - Include section documentation (for files)
• :show: - Show specific sections only
• :allow-dot-graphs: - Allow Graphviz dot graph rendering

Group Options (for doxygengroup)

• :inner: - Include inner groups recursively

Usage Examples

Basic Class Documentation

.. doxygenclass:: MyClass
   :members:
   :private-members:

Function with Specific Project

.. doxygenfunction:: processData
   :project: mylib

Namespace with Custom Sections

.. doxygennamespace:: math::geometry
   :show: public-func,public-type

File Documentation with Sections

.. doxygenfile:: utility.hpp
   :sections:
   :allow-dot-graphs:

Group with All Members

.. doxygengroup:: DataStructures
   :members:
   :undoc-members:
   :inner:

Base Directive Class

All breathe directives inherit from a common base class:

class BaseDirective(SphinxDirective):
    @property
    def directive_args(self) -> list
    
    @property  
    def project_info_factory(self) -> ProjectInfoFactory
    
    @property
    def parser_factory(self) -> DoxygenParserFactory
    
    @property
    def finder_factory(self) -> FinderFactory
    
    @property
    def filter_factory(self) -> FilterFactory
    
    @property
    def kind(self) -> str
    
    def create_warning(self, project_info: ProjectInfo | None, **kwargs) -> _WarningHandler
    
    def render(
        self, 
        node_stack, 
        project_info: ProjectInfo, 
        filter_: Filter, 
        target_handler: TargetHandler, 
        mask_factory: MaskFactoryBase, 
        directive_args
    ) -> list[nodes.Node]

The base class provides common functionality for project resolution, XML parsing, filtering, and rendering that all specific directives build upon.

Additional Configuration Options

Beyond the standard directive options, breathe provides additional configuration values that affect directive behavior:

# File extension handling for implementation files
breathe_implementation_filename_extensions = [".c", ".cc", ".cpp"]

# Member page organization
breathe_separate_member_pages = False

breathe_implementation_filename_extensions

Controls which file extensions are considered implementation files when processing file documentation. This affects how Doxygen processes source code files.

Type: List[str]
Default: [".c", ".cc", ".cpp"]

breathe_separate_member_pages

When enabled, creates separate documentation pages for class/struct members instead of including them inline with the container documentation.

Type: bool
Default: False