Overview¶
Exhale is an automatic C++ library API generation utility. It attempts to port the Doxygen hierarchy view presentations for classes and files into the Sphinx domain. See the Quickstart Guide for the bare minimum you need to give to integrate it into your project.
What does it do?¶
Exhale takes your Doxygen XML documentation and generates a large number of reStructuredText for you automatically. Most of the documents created are simply wrapper pages to use the various directives made available by Breathe.
It begins by explicitly parsing the Doxygen XML, and re-constructing the graph of
relationships. Things such as what file a given class was defined in, or what namespace
it belongs to. Once the graph has been reconstructed and traversed, the API
reStructuredText documents are generated and linked to one another, as well as the root
library document. The intent of the root library document is for you to just include it
in your top-level index toctree
directive. Refer to Additional Usage and Customization for
how the root library document will be presented as well as how to customize it.
The individual and root library page are an attempt to emulate the output of what
Doxygen would for their html class and file hierarchies. Many similarities exist, such
as the inclusion of struct
before class
in ranking over alphabetical. However,
I took a few liberties to change the output to include things I felt were more useful,
such as including enum
in the Class Hierarchy.
Note
Every generated file has a reStructuredText label that you can use to highlight specific items such as an important class or a file. Refer to Linking to a Generated File for more information.
What does it need to do that?¶
First and foremost, if you do not have valid Doxygen documentation, Exhale may produce false relationships, orphaned documents, etc. Generally speaking, if your Doxygen build is producing warnings, this is why Exhale is not creating what you expect.
Tip
Doxygen is a complex and advanced tool! In particular, you will likely need to finesse the Doxygen preprocessor for everything to work out as expected. Refer to the Doxygen Documentation Specifics section for more information.
From there, Exhale needs the following information, all provided in conf.py
:
You need to configure the Breathe extension’s
breathe_projects
variable.You need to configure the Breathe extension’s
breathe_default_project
variable.The containment folder exhale is allowed to assume control over. This is where all of the reStructuredText documents are being generated, and it must be a subdirectory of your Sphinx source directory (e.g., a subdirectory of the folder that your
conf.py
is in).The name of the root library document you want generated, which you will be including in a
toctree
directive somewhere.The title of the root library document, since it is part of a
toctree
.The path to strip from the Doxygen documentation. This is required since without it the full paths of files are used. Particularly for Read The Docs, this is rather unattractive.
This list sounds a lot more intimidating than it is. The way you should think of this list is more like this:
Exhale depends on the Breathe extension, so configure that correctly.
Exhale is generating a large number of documents for you, it needs to know where to put them. Since the user needs to include one of these documents in their own documentation, Exhale requires you to make these arguments explicitly so you are conscious of where they are getting put.
See the Quickstart Guide for getting everything up and running.