breathe

What it is and what it does

Breathe bridges Doxygen and Sphinx, two widely used but separate documentation tools. Doxygen parses C/C++ source code and generates detailed API reference material; Sphinx builds polished, long-form documentation in HTML, PDF, and other formats. Breathe lets you combine them by reading Doxygen's XML output and rendering it as reStructuredText directives inside your Sphinx build, so your API docs live alongside your user guides, tutorials, and conceptual material in a single coherent documentation site.

You run Doxygen once on your codebase to generate XML, configure Breathe to point to that XML, then use Breathe directives in your .rst files to pull in function signatures, class hierarchies, and parameter documentation. It's widely used in mature projects—PyTorch, NumPy, XGBoost, and others rely on it—and requires Python 3.9+, Sphinx 7.2+, and Doxygen 1.9.2+.

Use it for:

• Document a C/C++ library's public API alongside Python bindings or usage examples in a single Sphinx site.
• Maintain API reference for a compiled extension module without manually writing or updating signatures.
• Build unified docs for a polyglot project where some components are C/C++ and others are Python.
• Embed live Doxygen output in a ReadTheDocs or similar hosted documentation site.
• Generate searchable, cross-referenced API docs that stay in sync with source code changes.

Worth the install?

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

Breathe is a Sphinx plugin that renders Doxygen-generated documentation into your Sphinx documentation build, letting you embed API reference material from C/C++ code directly into user-facing docs.

Yes, if you have C/C++ code to document alongside Sphinx-based docs and are willing to run Doxygen as a prerequisite. It is stable, permissively licensed, and proven in production by major projects. The aging maintenance status (538 days since release) is a minor concern but not a blocker—the codebase is mature and the repository remains active. Install it if your documentation workflow already includes Doxygen; skip it if you're looking for pure Python API documentation.

Install

breathe on PyPI

pip install breathe

uv add breathe

poetry add breathe

Installing breathe

Before you install

Installs cleanly with only Sphinx as a runtime dependency. Maintenance is aging—last release was 538 days ago—but the repository is active and not archived, with established maintainers and a stable codebase used by major projects.

License in practice

Licensed under a permissive BSD license, so you can use Breathe freely in commercial and private projects without restriction or attribution requirement.

Quickstart

pip install breathe

In conf.py:
extensions = ['breathe']
reathe_projects = {'myproject': 'path/to/doxygen/xml'}

In your .rst file:
.. doxygenindex::
   :project: myproject

Requires Doxygen 1.9.2+ to be installed separately and run on your codebase to generate XML output before Breathe can process it.

Verify before relying

• Whether the 538-day gap since last release indicates planned maintenance cadence or stalled development.
• Compatibility with the latest Doxygen versions beyond 1.9.2.

Package facts

Evidence: breathe-4.36.0-py3-none-any.whl

Tags

More Software Development packages