Developer Reference Documentation

Todo

Exhale is being updated in waves as I have free time. It was originally written to be tracked by the user next to conf.py. Keeping it in a single file made this as convenient as possible for users, but was ultimately inconvenient to maintain.

Right now, the graph module is largely the same as it was in the single file library version. Eventually this will be whittled down into the other modules present in the library (e.g., modularizing writing nodes to file, parsing of xml).

Project Layout

The brief overview of what is where in this project:

Configs

The configs module contains everything related to what can be configured via conf.py, plus a few constants and book-keeping variables. At the bottom of this file is where you will find the bridge between Sphinx and Exhale (the function apply_sphinx_configurations()).

Deploy

The deploy module is responsible assisting in the creation of the Doxygen documentation (see exhaleExecutesDoxygen) as well as “exploding” the documentation into all of the various reStructuredText documents. The explode() is what triggers the creation of the graph, and is called by apply_sphinx_configurations().

Graph

The graph module is the main representation of all the various items being documented. This is by far the most important, and confusing, module. The brief version is that the explode() function will create an ExhaleRoot object, which could be thought of as the equivalent of the index.xml produced by Doxygen. The ExhaleRoot object will parse the Doxygen xml files and instantiate ExhaleNode objects to represent the different items being documented.

Parse

The parse module does not currently do the parsing you would think. It currently only parses the file level documentation from the xml documents and gives a best-faith effort to turn this into valid reStructuredText.

The future intent is to have the parsing done in the graph module get stripped out and placed in this module.

Utils

The utils module contains various helper methods for consistent formatting, colorized error reporting, and serialization of the Exhale configurations (Sphinx requires this in order to pickle the environment / identify what has changed, etc).

Execution Flow

There are quite a few different moving parts involved with this project, but when you build your documentation with make html, the Sphinx build process gets launched and the following (simplified, read the Sphinx docs for the full story) occurs:

1. Sphinx reads conf.py and determines which extensions to find / load. The user of Exhale should have both breathe and exhale in this list.

2. Each extension is setup, whereby the extension declares what variables it is expecting (or can support) for customization that the user will be putting in their conf.py. During this phase is when extensions also request to be signaled when different stages of the Sphinx build process are triggered.

   • Exhale requests notification of the builder-inited event, which is the first event where the configuration variables have been populated.

   • It would be nice to one-day support incremental builds and a clean target, but at this time I have no idea how to do these.

   • As far as I understand it, the Exhale must complete generating all of the reStructuredText documents before the env-get-outdated event is triggered.

     Note

     If you have suggestions of a better way to hook into Sphinx, or ideas on how to only regenerate documents that need to be updated (hard), please raise an issue on GitHub.

     Even if you don’t have a solution, it would be great to hear of ideas!

3. Now that the extensions have been setup, the rest of conf.py is processed. For all intensive purposes, you can assume that as soon as this is complete is when Exhale is getting launched.

4. If requested, Exhale will first execute Doxygen. Afterward, it will generate all of the various reStructuredText documents.

5. Control is passed back to Sphinx and then the source for the documentation is searched for / parsed from the Sphinx source directory (generally wherever your conf.py is, as well as all nested directories).

In picture form:

Full Reference Documentation

• Exhale Configs Module
  • Required Configuration Arguments
    • Required Arguments for Breathe
    • Required Arguments for Exhale
  • Optional Configuration Arguments
    • Heavily Encouraged Optional Configuration
    • Build Process Logging, Colors, and Debugging
    • Root API Document Customization
    • Manual Indexing
    • Clickable Hierarchies
    • Page Level Customization
      • Using Contents Directives
    • Breathe Customization
    • Doxygen Execution and Customization
  • Programlisting Customization
  • Utility Variables
  • Secondary Sphinx Entry Point
• Exhale Deploy Module
  • Doxygen Execution Functions
  • Library API Generation
• Exhale Graph Module
  • Helper Class ExhaleNode Reference
  • Primary Class ExhaleRoot Reference
• Exhale Parse Module
• Exhale Utils Module
  • Breathe Customization Support
  • Unsorted Misc
  • Template Parsing