Automatic C++ library API documentation generator using Doxygen, Sphinx, and Breathe. Exhale revives Doxygen’s class / file hierarchies using reStructuredText for superior markup syntax / websites.
There is a reason why Exhale is development status 2 as far as
pip is concerned.
It is functional enough that it should work for your project, but there are a number
of features I still intend to implement when there is more time.
Exhale is a Sphinx extension that depends on
the excellent Breathe extension which enables parsing Doxygen documentation into the
Sphinx domain. Exhale provides a layer of automation, enabling launching Doxygen and
generating the full website all from your
conf.py. Exhale will execute these
actions by way of
sphinx-build being invoked, allowing you to use it for hosting on
Read the Docs. Exhale was designed for generating html
output, and may not be appropriate for other builders provided by Sphinx.
See it in Action¶
The ExhaleCompanion repository has three builds to demonstrate the different options with respect to creating a Tree View, as well as details of specific HTML Theme choices:
|HTML Theme Choice||TreeView Created||ExhaleCompanion Docs|
Exhale is a Sphinx Extension that depends on Breathe for access to the Doxygen reStructuredText directives, and both BeautifulSoup and lxml for parsing the generated Doxygen XML documentation. Exhale also uses six help account for the Python 2 unicode dilemma. The easiest way to install Exhale is:
$ pip install exhale
This will install Exhale, as well as all of its dependencies. You are of course capable
of installing Exhale through other means, as it contains a
setup.py. If you choose
to do this, I assume you know what you are doing (and will provide neither instructions
nor support for alternative installation strategies).
If you fail
pip install exhale and it is failing on
lxml, you will likely
need to install the proper development libraries. See the
lxml installation instructions for possible fixes.
lxml is readily available for Read The Docs and generally installs
seamlessly for Unix systems, but my understanding is Windows users may need to put a
little more effort in to get it to install.
Exhale might not be the tool you are looking for! It was designed to be as intuitive and flexible as possible, but it does require more machinery to get everything started.
- Why use it?
- You would use Exhale if you want to have beautiful Sphinx generated websites, but also see the value of the Class and File hierarchies provided by Doxygen. From running Doxygen for you, to organizing your full API every time, you won’t need to worry about your documentation getting out of sync with the code — it’s regenerated on the fly every time.
- Why not use it?
It may be more involved than you need. Check out the
breathe-apidoctool that comes with your installation of
breathe. It is quite similar to the Sphinx API doc tool, and that may be all you are looking for to get your documentation displayed.
If you are working with a small enough framework, you may also be satisfied with just using the
.. autodoxygenindex::directive from
breathe. It works very well!
- The Main Difference
The Class and File hierarchies are only available in Sphinx via Exhale 😊
Depending on the size and complexity of your project,
autodoxygenindexmay be more appropriate.
- Developer Reference Documentation
- Mastering Doxygen
- Nothing is working, where did I go wrong?
- Can I use the formidable Intersphinx extension?
- Why does it build locally, but not on Read the Docs?
- Why are there build warnings about generated files not being included?
- Unicode support?
- Why does my documentation take so long to build?
- Why are the Sphinx RTD theme “Edit on GitHub” links are invalid?
- Metaprogramming and template (specialization)?
- How can I get Doxygen to skip code it cannot process?
- I thought reStructuredText was supported, why does it look weird?
- You aren’t including my
defines, etc. Why Not?
- Why aren’t my Classes, Structs, Enums, or Unions associated with the right file?
- My documentation is setup using groups, how can I use Exhale?
- Ok seriously, why is there SO MUCH documentation on a documentation system?
- Testing Suite
This project could not exist without the already excellent tools available: Doxygen, Sphinx, Breathe, and many others. In particular, though, for the Tree View hierarchies to be successful, I vendor copies of two excellent libraries that I make no claims to. They are vendored with your installation of Exhale, in accordance with each project’s license:
For non-bootstrap, I used Kate Morley’s excellent and lightweight collapsibleLists including the sample CSS / images on that post. She includes a generous CC0 1.0 license for these files, as well as the rest of her website.
For every HTML Theme I have tried, except for ones using bootstrap, this library works reliably and consistently. It matches the Sphinx RTD theme quite well, too!
This library is exceptionally well thought out and enables an impressive amount of customization. At this time, Exhale does not expose any of the available customizations. If there is a specific one you’d like to see, please join the discussion here.
Both of these libraries and copies of their licenses can be found in the data folder of the source code.