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 viaconf.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 functionapply_sphinx_configurations()
).- Deploy
The
deploy
module is responsible assisting in the creation of the Doxygen documentation (seeexhaleExecutesDoxygen
) as well as “exploding” the documentation into all of the various reStructuredText documents. Theexplode()
is what triggers the creation of the graph, and is called byapply_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 theexplode()
function will create anExhaleRoot
object, which could be thought of as the equivalent of theindex.xml
produced by Doxygen. TheExhaleRoot
object will parse the Doxygen xml files and instantiateExhaleNode
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:
Sphinx reads
conf.py
and determines whichextensions
to find / load. The user of Exhale should have bothbreathe
andexhale
in 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 theirconf.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!
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.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.py
is, as well as all nested directories).
In picture form:
Full Reference Documentation
- Exhale Configs Module
- Required Configuration Arguments
- Optional Configuration Arguments
- Heavily Encouraged Optional Configuration
- Build Process Logging, Colors, and Debugging
- Root API Document Customization
- Manual Indexing
- Clickable Hierarchies
createTreeView
minifyTreeView
treeViewIsBootstrap
treeViewBootstrapTextSpanClass
treeViewBootstrapIconMimicColor
treeViewBootstrapOnhoverColor
treeViewBootstrapUseBadgeTags
treeViewBootstrapExpandIcon
treeViewBootstrapCollapseIcon
treeViewBootstrapLevels
_class_hierarchy_id
_file_hierarchy_id
_page_hierarchy_id
_bstrap_class_hierarchy_fn_data_name
_bstrap_file_hierarchy_fn_data_name
_bstrap_page_hierarchy_fn_data_name
- Page Level Customization
- Breathe Customization
- Doxygen Execution and Customization
- Programlisting Customization
- Utility Variables
- Secondary Sphinx Entry Point
- Exhale Deploy Module
- Exhale Graph Module
- Helper Class ExhaleNode Reference
ExhaleNode
ExhaleNode.__init__()
ExhaleNode.__lt__()
ExhaleNode.__repr__()
ExhaleNode.set_owner()
ExhaleNode.breathe_identifier()
ExhaleNode.full_signature()
ExhaleNode.templateParametersStringAsRestList()
ExhaleNode.baseOrDerivedListString()
ExhaleNode.findNestedNamespaces()
ExhaleNode.findNestedDirectories()
ExhaleNode.findNestedClassLike()
ExhaleNode.findNestedEnums()
ExhaleNode.findNestedUnions()
ExhaleNode.toConsole()
ExhaleNode.typeSort()
ExhaleNode.inPageHierarchy()
ExhaleNode.inClassHierarchy()
ExhaleNode.inFileHierarchy()
ExhaleNode.toHierarchy()
ExhaleNode.__weakref__
- Primary Class ExhaleRoot Reference
ExhaleRoot
ExhaleRoot.__init__()
ExhaleRoot.parse()
ExhaleRoot.discoverAllNodes()
ExhaleRoot.trackNodeIfUnseen()
ExhaleRoot.reparentAll()
ExhaleRoot.reparentUnions()
ExhaleRoot.reparentClassLike()
ExhaleRoot.reparentDirectories()
ExhaleRoot.renameToNamespaceScopes()
ExhaleRoot.reparentNamespaces()
ExhaleRoot.fileRefDiscovery()
ExhaleRoot.filePostProcess()
ExhaleRoot.parseFunctionSignatures()
ExhaleRoot.sortInternals()
ExhaleRoot.deepSortList()
ExhaleRoot.generateFullAPI()
ExhaleRoot.generateAPIRootHeader()
ExhaleRoot.generateNodeDocuments()
ExhaleRoot.initializeNodeFilenameAndLink()
ExhaleRoot.generateSingleNodeRST()
ExhaleRoot.generatePageDocuments()
ExhaleRoot.generateSinglePageDocument()
ExhaleRoot.generateNamespaceNodeDocuments()
ExhaleRoot.generateSingleNamespace()
ExhaleRoot.generateNamespaceChildrenString()
ExhaleRoot.generateSortedChildListString()
ExhaleRoot.generateFileNodeDocuments()
ExhaleRoot.generateDirectoryNodeDocuments()
ExhaleRoot.generateDirectoryNodeRST()
ExhaleRoot.generateAPIRootBody()
ExhaleRoot.gerrymanderNodeFilenames()
ExhaleRoot.generateViewHierarchies()
ExhaleRoot.generatePageView()
ExhaleRoot.generateClassView()
ExhaleRoot.generateDirectoryView()
ExhaleRoot.generateUnabridgedAPI()
ExhaleRoot.enumerateAll()
ExhaleRoot.toConsole()
ExhaleRoot.consoleFormat()
ExhaleRoot.__weakref__
- Helper Class ExhaleNode Reference
- Exhale Parse Module
- Exhale Utils Module
AVAILABLE_KINDS
LEAF_LIKE_KINDS
contentsDirectiveOrNone()
- Breathe Customization Support
- Unsorted Misc
heading_mark()
nodeCompoundXMLContents()
qualifyKind()
kindAsBreatheDirective()
specificationsForKind()
AnsiColors
indent()
prefix()
exclaim()
colorize()
_use_color()
progress()
info()
critical()
verbose_log()
__fancy()
fancyErrorString()
fancyError()
LANG_TO_LEX
doxygenLanguageToPygmentsLexer()
sanitize()
sanitize_all()
- Template Parsing