doxygen.rst

toc-depth:	4

Doxygen

The Breathe extension integrates Doxygen-generated documentation into Sphinx.

Supported languages

Breathe supports any language that Doxygen can parse:

• C
• C++
• C#
• Objective-C
• PHP
• Java
• Python (limited)
• Fortran
• VHDL

Setup

Install Breathe:

pip install breathe

Configure Doxygen to generate XML output in your Doxyfile:

GENERATE_XML = YES
XML_OUTPUT = xml

Add Breathe to your conf.py:

extensions = ['breathe']

breathe_projects = {
    'myproject': './doxygen/xml/'
}
breathe_default_project = 'myproject'

Basic usage

Document a class

.. doxygenclass:: DatabaseConnection
   :members:

.. doxygenclass:: DatabaseConnection
   :members:

Document a function

.. doxygenfunction:: format_query

.. doxygenfunction:: format_query

Common options

Select specific members

.. doxygenclass:: DatabaseConnection
   :members: connect, disconnect

Include private members

.. doxygenclass:: DatabaseConnection
   :members:
   :private-members:

Include undocumented members

.. doxygenclass:: DatabaseConnection
   :members:
   :undoc-members:

Doxygen comment syntax

C++ example

/**
 * @brief Establishes a connection
 * @param host The database host address
 * @param port The database port number
 * @return true if connection successful
 * @throw ConnectionError if connection fails
 */
bool connect(const std::string& host, int port);

C example

/**
 * @brief Connect to database
 * @param[in] config Connection configuration
 * @return Connection handle or NULL on failure
 */
connection_t* db_connect(const connection_config_t* config);

Configuration

Common settings in conf.py:

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

Automatic API generation

For large projects, use Exhale to automatically generate API documentation pages:

pip install exhale

Configure in conf.py:

extensions = ['breathe', 'exhale']

exhale_args = {
    'containmentFolder': './api',
    'rootFileName': 'library_root.rst',
    'rootFileTitle': 'API Reference',
    'doxygenStripFromPath': '..',
}

Exhale will automatically create a page for each class, function, and file in your project.