Developer Reference Documentation
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).
The brief overview of what is where in this project:
configsmodule 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
deploymodule 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
graphmodule 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
ExhaleRootobject, which could be thought of as the equivalent of the
index.xmlproduced by Doxygen. The
ExhaleRootobject will parse the Doxygen xml files and instantiate
ExhaleNodeobjects to represent the different items being documented.
parsemodule 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
graphmodule get stripped out and placed in this module.
utilsmodule 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).
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:
conf.pyand determines which
extensionsto find / load. The user of Exhale should have both
exhalein this list.
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.
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!
Now that the extensions have been setup, the rest of
conf.pyis processed. For all intensive purposes, you can assume that as soon as this is complete is when Exhale is getting launched.
If requested, Exhale will first execute Doxygen. Afterward, it will generate all of the various reStructuredText documents.
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.pyis, as well as all nested directories).
In picture form:
Full Reference Documentation
- Exhale Configs Module
- Required Configuration Arguments
- Optional Configuration Arguments
- Programlisting Customization
- Utility Variables
- Secondary Sphinx Entry Point
- Exhale Deploy Module
- Exhale Graph Module
- Exhale Parse Module
- Exhale Utils Module