{"id":3424,"library":"breathe","title":"Breathe","description":"Breathe is a Sphinx plugin that provides a bridge between the Sphinx documentation system and Doxygen's XML output. It allows users to integrate Doxygen's comprehensive technical documentation of C, C++, and other languages directly into Sphinx-generated documentation, offering an 'autodoc'-like experience for non-Python projects. The current stable version is 4.36.0, with releases typically occurring a few times a year to maintain compatibility with Sphinx and Doxygen updates.","status":"active","version":"4.36.0","language":"en","source_language":"en","source_url":"https://github.com/breathe-doc/breathe/","tags":["sphinx","documentation","doxygen","c++","c","python","extension"],"install":[{"cmd":"pip install breathe","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Runtime environment.","package":"python","version":">=3.9"},{"reason":"Core dependency as a Sphinx extension.","package":"sphinx","version":">=7.2"},{"reason":"Required to generate the XML output that Breathe consumes.","package":"doxygen","version":">=1.9.2"}],"imports":[{"note":"Breathe is a Sphinx extension, not a Python module imported directly in user code for typical usage. It is activated by adding 'breathe' to the 'extensions' list in Sphinx's conf.py.","wrong":"import breathe","symbol":"breathe","correct":"extensions = ['sphinx.ext.autodoc', 'breathe']"}],"quickstart":{"code":"# 1. In your Doxyfile (generated by Doxygen -g), ensure:\n#    GENERATE_XML = YES\n# 2. In your Sphinx conf.py:\nimport os\n\nproject = 'MyProject'\ncopyright = '2026, MyName'\nauthor = 'MyName'\n\nextensions = [\n    'sphinx.ext.autodoc',\n    'breathe'\n]\n\n# Path to the directory containing Doxygen's XML output\nbreathe_projects = {\n    \"myproject\": os.path.abspath(os.path.join(os.path.dirname(__file__), \"_build/doxygen/xml\"))\n}\n\nbreathe_default_project = \"myproject\"\n\n# 3. In an .rst file (e.g., index.rst or a new file like api.rst):\n# .. doxygenclass:: MyNamespace::MyClass\n#    :project: myproject\n#    :members:\n#\n# .. doxygenfunction:: my_function(int, int)\n#    :project: myproject","lang":"python","description":"To use Breathe, first configure Doxygen to generate XML output (`GENERATE_XML = YES`). Then, in your Sphinx `conf.py`, add `breathe` to your `extensions` list and configure `breathe_projects` to point to your Doxygen XML output directory. Finally, use Breathe's reStructuredText directives (e.g., `.. doxygenclass::`, `.. doxygenfunction::`) in your `.rst` files to include the Doxygen documentation."},"warnings":[{"fix":"Upgrade Python to 3.9+ or pin `breathe<4.36.0` (e.g., `breathe==4.35.0`) if Python upgrade is not feasible.","message":"Breathe v4.36.0 and later require Python 3.9 or higher. Earlier versions supported Python 3.7+ (e.g., v4.35.0). Projects on older Python versions will need to upgrade Python or pin Breathe to an older compatible version.","severity":"breaking","affected_versions":">=4.36.0"},{"fix":"Upgrade Sphinx to 7.2+ or pin `breathe` and `sphinx` to mutually compatible older versions.","message":"Breathe v4.36.0 and later require Sphinx 7.2 or higher. Earlier versions had compatibility with older Sphinx versions (e.g., v4.35.0 added support for Sphinx 6, fixed tests for Sphinx 5.3). Ensure your Sphinx installation meets this requirement.","severity":"breaking","affected_versions":">=4.36.0"},{"fix":"Ensure your Doxyfile contains `GENERATE_XML = YES` and that Doxygen is run to produce the XML files in the directory specified by `breathe_projects`.","message":"Breathe relies entirely on Doxygen's XML output. If Doxygen is not run correctly with `GENERATE_XML = YES` enabled in its configuration file (Doxyfile), Breathe will not find any documentation to render.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Double-check that the paths in `breathe_projects` correctly point to the Doxygen XML output directories and that the project names used in directives (e.g., `:project: myproject`) match the keys in `breathe_projects`.","message":"Incorrectly configured `breathe_projects` paths or `breathe_default_project` names are common sources of 'project not found' or 'file not found' errors. The paths must be absolute or correctly relative to `conf.py`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always pin to a specific major/minor version (e.g., `pip install 'breathe<5'`) or a precise version (`pip install breathe==4.36.0`) to avoid inadvertently upgrading to pre-release versions.","message":"While v4.36.0 is the current stable release, alpha versions like `v5.0.0a2` are available. Installing without version pinning (`pip install breathe`) may lead to unexpected changes or instabilities if a new major alpha becomes the 'latest' on PyPI.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}