exhale

What it is and what it does

Exhale is a Sphinx extension that bridges Doxygen and Sphinx by automatically running Doxygen on your C++ source, parsing the generated XML with BeautifulSoup and lxml, and reconstructing Doxygen's class, file, and page hierarchies as reStructuredText documents. This allows you to publish C++ API documentation with Sphinx's styling and navigation while preserving the structural organization that Doxygen provides—something Breathe alone does not offer.

The package is designed for projects that want beautiful Sphinx-generated websites but also value Doxygen's hierarchical organization. It regenerates documentation on every build, keeping it automatically in sync with code changes. However, it requires more setup machinery than simpler alternatives like Breathe's autodoxygenindex directive or breathe-apidoc, and the documentation notes it works well on small-to-medium projects; larger projects may face performance or complexity challenges due to the large number of .rst files Exhale generates.

Use it for:

• Generate browsable C++ API docs with Sphinx styling and Doxygen's class/file hierarchies for a medium-sized library.
• Maintain automatically synchronized API documentation that regenerates whenever source code changes.
• Publish C++ reference docs alongside prose documentation in a unified Sphinx site.
• Create tree-view navigation of C++ classes and files in RTD Theme or Bootstrap Theme Sphinx sites.
• Avoid manual synchronization between Doxygen and Sphinx by automating the full pipeline.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Exhale automatically generates C++ API documentation by running Doxygen, parsing its XML output with BeautifulSoup and lxml, and publishing class, file, and page hierarchies as reStructuredText documents within Sphinx.

Yes, if you need C++ API documentation with Doxygen's hierarchies in Sphinx and your project is small to medium-sized. The low install friction, permissive license, and zero known vulnerabilities make it safe to try. However, dormant maintenance (last release 2024-01-21) and the documented limitation to small-to-medium projects are real constraints—verify compatibility with your Sphinx/Breathe versions and test on a realistic project before committing to it for large codebases.

Install

exhale on PyPI

pip install exhale

uv add exhale

poetry add exhale

Installing exhale

Before you install

Low friction: pure Python wheel with five runtime dependencies (Sphinx, Breathe, BeautifulSoup4, lxml, six). Maintenance is dormant—last release 2024-01-21, no commits since 2024-08-09, and no recent activity, though the repository remains active and has 239 stars.

License in practice

BSD 3-Clause (permissive) license allows commercial and private use with minimal restrictions. The package also vendors two third-party libraries (collapsibleLists under CC0 1.0 and bootstrap-treeview under Apache v2) with copies of their licenses included in the data folder.

Quickstart

pip install exhale

# In conf.py (Sphinx configuration):
extensions = ['exhale']
exhale_args = {
    'containmentFolder': './api',
    'rootFileName': 'library_root.rst',
    'rootFileTitle': 'Library API',
    'doxygenStripFromPath': '..',
    'exhaleExecutesDoxygen': True,
    'exhaleDoxygenStdin': 'INPUT = ../include\nFILE_PATTERNS = *.hpp'
}

Requires Doxygen installed and on PATH; Sphinx >=4.3.2, Breathe >=4.33.1, and Python >=3.8.

Verify before relying

• Whether dormant maintenance (last release 2024-01-21, 936 days ago) affects compatibility with current Sphinx/Breathe versions.
• Performance and scalability limits for projects larger than 'medium-sized' (documentation mentions small-to-medium projects work well).
• Whether the vendored collapsibleLists and bootstrap-treeview libraries are kept in sync with upstream.

Package facts

Evidence: exhale-0.3.7-py3-none-any.whl

Tags

More Sphinx packages