Exhale: Automatic C++ API Documentation Generator

Common errors

• Exhale is not creating expected API documentation / malformed output.

  cause Underlying Doxygen documentation has warnings or errors, leading to incorrect XML output that Exhale then processes incorrectly.
  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.

• Failed to install `lxml` dependency during `pip install exhale`.

  cause The `lxml` package has system-level dependencies (like `libxml2` and `libxslt`) which might be missing, particularly on Windows or minimal Linux environments.
  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).

• Generated API pages are not appearing in the Sphinx build output or linked in the navigation.

  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.
  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`.

• Duplicate functions/classes or incomplete information displayed in the Sphinx sidebar/API output.

  cause Doxygen configuration issues leading to duplicate entries in the XML or Exhale misinterpreting relationships due to ambiguous Doxygen output.
  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.

Warnings

• breaking 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.
  Fix: Upgrade to Python 3.8+ and ensure Sphinx (>=2.0) and Breathe (>=4.13.0) are installed for `exhale>=0.3.0`.
• breaking The internal link generation scheme changed significantly in v0.2.0, potentially breaking existing internal links in documentation.
  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.
• gotcha 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.
  Fix: Always resolve all Doxygen warnings and errors in your C++ project before generating documentation with Exhale.
• gotcha Windows users may encounter issues with excessively long file paths generated by Doxygen/Sphinx, even if Exhale attempts to handle them.
  Fix: Build documentation in a higher-level directory (e.g., `C:\your_project`) to reduce path length issues, especially on Windows.
• gotcha 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`).
  Fix: Set `containmentFolder` to a dedicated subdirectory, e.g., `./api`, within your Sphinx source directory.

Install

• pip install exhale Install Exhale and its Python dependencies
• pip install sphinx>=2.0 breathe>=4.13.0 exhale Recommended for Python 3.5+ to ensure compatible dependencies

Imports

• generate

  from exhale import generate

  Typically called from within the `setup(app)` function in `conf.py`.

Quickstart

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.

import os
import sys

# Add these to your conf.py after `extensions` list and other configurations
# Assuming your Doxygen XML output is in `_build/doxyoutput/xml` relative to docs/conf.py
# and your C++ source is in `../include` relative to docs/

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.viewcode',
    'breathe',
    'exhale'
]

# Breathe configuration
breathe_projects = {"My Project": "_build/doxyoutput/xml"}
breathe_default_project = "My Project"

# Exhale configuration
exhale_args = {
    "doxygenIndexXMLPath": "_build/doxyoutput/xml/index.xml",
    "containmentFolder": "./api",
    "rootFileName": "library_root.rst",
    "rootFileTitle": "Library API",
    "doxygenStripFromPath": "..",
    "createTreeView": True,
    "exhaleExecutesDoxygen": True,
    "exhaleDoxygenStdin": "INPUT = ../../include"
}

# Tell sphinx what the primary language being documented is.
primary_domain = 'cpp'
# Tell sphinx what the pygments highlight language should be.
highlight_language = 'cpp'

# If you choose to execute Doxygen separately, remove 'exhaleExecutesDoxygen' and 'exhaleDoxygenStdin'
# and ensure Doxygen output is generated before Sphinx build.

# Add 'api/library_root' to a toctree directive in your index.rst, e.g.:
#
# .. toctree::
#    :maxdepth: 2
#    :caption: Contents:
#
#    api/library_root