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

Install

exhale on PyPI

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.

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

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'
}

Package facts

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

Tags

More Sphinx packages

See also breathe · autodoc_pydantic · CppHeaderParser · autodocsumm · sphinx-autodoc2 · sphinxcontrib-applehelp · sphinx_design · sphinx_mdinclude · pydoctor