{"id":7209,"library":"exhale","title":"Exhale: Automatic C++ API Documentation Generator","description":"Exhale is a Sphinx extension designed to automatically generate C++ library API documentation. It integrates Doxygen's XML output with Sphinx, providing features like class, file, and page hierarchies within Sphinx-generated websites. Currently at version 0.3.7, Exhale is actively maintained with releases focusing on bug fixes and dependency updates.","status":"active","version":"0.3.7","language":"en","source_language":"en","source_url":"https://github.com/svenevs/exhale","tags":["documentation","sphinx","doxygen","c++","api-generation","extension"],"install":[{"cmd":"pip install exhale","lang":"bash","label":"Install Exhale and its Python dependencies"},{"cmd":"pip install sphinx>=2.0 breathe>=4.13.0 exhale","lang":"bash","label":"Recommended for Python 3.5+ to ensure compatible dependencies"}],"dependencies":[{"reason":"Required Python package; Exhale is a Sphinx extension.","package":"sphinx","optional":false},{"reason":"Required Python package for parsing Doxygen XML into Sphinx directives.","package":"breathe","optional":false},{"reason":"Required external C++ documentation tool to generate XML input for Exhale.","package":"doxygen","optional":false},{"reason":"Python dependency for parsing generated Doxygen XML documentation.","package":"beautifulsoup4","optional":false},{"reason":"Python dependency for parsing generated Doxygen XML documentation.","package":"lxml","optional":false},{"reason":"Python dependency, historically for Python 2/3 compatibility, though Exhale 0.3.x requires Python 3.8+.","package":"six","optional":false}],"imports":[{"note":"Typically called from within the `setup(app)` function in `conf.py`.","symbol":"generate","correct":"from exhale import generate"}],"quickstart":{"code":"import os\nimport sys\n\n# Add these to your conf.py after `extensions` list and other configurations\n# Assuming your Doxygen XML output is in `_build/doxyoutput/xml` relative to docs/conf.py\n# and your C++ source is in `../include` relative to docs/\n\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.autosummary',\n    'sphinx.ext.doctest',\n    'sphinx.ext.intersphinx',\n    'sphinx.ext.viewcode',\n    'breathe',\n    'exhale'\n]\n\n# Breathe configuration\nbreathe_projects = {\"My Project\": \"_build/doxyoutput/xml\"}\nbreathe_default_project = \"My Project\"\n\n# Exhale configuration\nexhale_args = {\n    \"doxygenIndexXMLPath\": \"_build/doxyoutput/xml/index.xml\",\n    \"containmentFolder\": \"./api\",\n    \"rootFileName\": \"library_root.rst\",\n    \"rootFileTitle\": \"Library API\",\n    \"doxygenStripFromPath\": \"..\",\n    \"createTreeView\": True,\n    \"exhaleExecutesDoxygen\": True,\n    \"exhaleDoxygenStdin\": \"INPUT = ../../include\"\n}\n\n# Tell sphinx what the primary language being documented is.\nprimary_domain = 'cpp'\n# Tell sphinx what the pygments highlight language should be.\nhighlight_language = 'cpp'\n\n# If you choose to execute Doxygen separately, remove 'exhaleExecutesDoxygen' and 'exhaleDoxygenStdin'\n# and ensure Doxygen output is generated before Sphinx build.\n\n# Add 'api/library_root' to a toctree directive in your index.rst, e.g.:\n#\n# .. toctree::\n#    :maxdepth: 2\n#    :caption: Contents:\n#\n#    api/library_root\n","lang":"python","description":"To quickly integrate Exhale, first run `sphinx-quickstart` in your documentation directory. Then, modify your `conf.py` to include `breathe` and `exhale` in your extensions. Configure `breathe_projects`, `breathe_default_project`, and the `exhale_args` dictionary. Ensure Doxygen XML output is correctly configured. Finally, link the generated API root file (`api/library_root.rst` by default) into your main `index.rst` using a `toctree` directive."},"warnings":[{"fix":"Upgrade to Python 3.8+ and ensure Sphinx (>=2.0) and Breathe (>=4.13.0) are installed for `exhale>=0.3.0`.","message":"Exhale dropped support for Python 2.7 in versions 0.3.x. Users must use Python 3.7+ (recommended 3.8+). Compatibility with specific Sphinx and Breathe versions is also critical.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Review and update internal links if upgrading from `exhale<0.2.0`. The current scheme is more stable but may still require adjustments if previous versions are heavily relied upon.","message":"The internal link generation scheme changed significantly in v0.2.0, potentially breaking existing internal links in documentation.","severity":"breaking","affected_versions":"0.2.0-0.3.x"},{"fix":"Always resolve all Doxygen warnings and errors in your C++ project before generating documentation with Exhale.","message":"Exhale's output heavily depends on valid Doxygen XML. Warnings or errors in your Doxygen build will likely result in unexpected, incorrect, or incomplete API documentation from Exhale.","severity":"gotcha","affected_versions":"All"},{"fix":"Build documentation in a higher-level directory (e.g., `C:\\your_project`) to reduce path length issues, especially on Windows.","message":"Windows users may encounter issues with excessively long file paths generated by Doxygen/Sphinx, even if Exhale attempts to handle them.","severity":"gotcha","affected_versions":"All"},{"fix":"Set `containmentFolder` to a dedicated subdirectory, e.g., `./api`, within your Sphinx source directory.","message":"The `containmentFolder` for Exhale's generated reStructuredText files *must* be a subdirectory of your Sphinx source directory and cannot be the root (`.`) or the Sphinx build output directory (`_build`).","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Inspect your Doxygen build logs and resolve all warnings and errors in your C++ code's Doxygen comments and configuration. Exhale's output fidelity is directly tied to Doxygen's accuracy.","cause":"Underlying Doxygen documentation has warnings or errors, leading to incorrect XML output that Exhale then processes incorrectly.","error":"Exhale is not creating expected API documentation / malformed output."},{"fix":"Refer to the `lxml` installation documentation for specific system-level library requirements and how to install them for your operating system. For many Linux systems, this involves `apt-get install libxml2-dev libxslt1-dev` (Debian/Ubuntu) or `yum install libxml2-devel libxslt-devel` (RHEL/Fedora).","cause":"The `lxml` package has system-level dependencies (like `libxml2` and `libxslt`) which might be missing, particularly on Windows or minimal Linux environments.","error":"Failed to install `lxml` dependency during `pip install exhale`."},{"fix":"Ensure `exhale_args['containmentFolder']` points to a *subdirectory* of your Sphinx source directory (e.g., `./api`) and that your main `index.rst` (or equivalent) contains a `.. toctree::` directive linking to this root, e.g., `api/library_root`.","cause":"The `containmentFolder` specified in `exhale_args` is not a valid location (e.g., it's set to the Sphinx source root or the build directory), or the `library_root.rst` is not included in an `index.rst` toctree.","error":"Generated API pages are not appearing in the Sphinx build output or linked in the navigation."},{"fix":"Review your Doxygen configuration, especially `INPUT`, `FILE_PATTERNS`, and `EXCLUDE` settings, to ensure only desired files are processed once. Address any Doxygen warnings about ambiguous documentation.","cause":"Doxygen configuration issues leading to duplicate entries in the XML or Exhale misinterpreting relationships due to ambiguous Doxygen output.","error":"Duplicate functions/classes or incomplete information displayed in the Sphinx sidebar/API output."}]}