Breathe

This is an extension to reStructuredText and Sphinx to be able to read and render the Doxygen xml output.

Download

Breathe is available from github and PyPI, the Python Package Index

Documentation

The documentation is available here. Thank you to the people running Read the Docs for such an excellent service.

The source for the documentation is in the documentation folder if you want to built it and read it locally.

Testing

Breathe doesn't have a set of tests at the moment. The documentation does a good job of running the different parts of the Breathe functionality but there is nothing to check that the output is appropriate.

To build the documentation, run make in the root of the project.

This will run doxygen over the example code and then run the Breathe documentation. View the results at:

documentation/build/html/index.html

Requirements

Development is currently done with:

• Python 2.7.4
• Docutils 0.11
• Sphinx 1.2.2
• Doxygen 1.8.4

Doxygen 1.5.1 seems to produce xml with repeated sections which causes Breathe some confusion. Not sure when this was resolved but it might be best to go for the latest possible.

Mailing List

There is a mailing list available thanks to LibreList:

breathe@librelist.com

The archives are available here.

Examples

Examples of Breathe used by other projects:

• cppformat

If you have an example you would like listed here, please make a github issue with the details.

Credits

Thank you to:

• nijel
• sebastianschaetz
• mbolivar
• queezythegreat
• abingham
• davidm
• hobu
• magro11
• scopatz
• vitaut
• vonj
• jmnas
• donkopotamus
• jo3w4rd
• Anthony Truchet
• Daniel Matz
• Andrew Hundt
• sebastinas
• robo9k
• sieben
• rweickelt

For their contributions; reporting issues and improving the code and documentation. And thanks to:

• Dimitri van Heesch for Doxygen.
• Georg Brandl for Sphinx.
• David Goodger for Docutils and reStructuredText.

Change Log

• Changes since the last release
  • Improved :members: implementation to handle inner classes properly.
  • Updated doxygenstruct to share the doxygenclass implementation path which grants it the options from doxygenclass directive.
  • Added :outline: option support to doxygengroup & doxygennamespace directives.
  • Added doxygennamespace directive.
  • Added :undoc-members: option to doxygenclass & doxygengroup directives.
  • Breaking change: Removed :sections: option for doxygenclass & doxygengroup directives and replaced it with :members:, :protected-members: and :private-members:, and changed breathe_default_sections config variable to breathe_default_members. This is designed to more closely match the Sphinx autodoc functionality and interface.
• Breathe v2.0.0
  • Add compare script for checking changes to documentation caused by changes in the implementation.
  • Switched to https reference for MathJax Javascript.
  • Breaking change: Change autodoxygen* directives to require explicitly declared source files in the conf.py rather than attempting to detect them from the directive arguments.
  • Switch documentation hosting to ReadTheDocs.org.
  • Breaking change: Switch to assuming all relative paths are relative to the directory holding the conf.py file. Previously, it would assume they were relative to the user's current working directory. This breaks projects which use separate build & source directories.
  • Add doxygenunion directive.
  • Add doxygengroup directive.
  • Add support for lists in the output. They were previously ignored.
  • Updated implementation to use the docutils nodes that Sphinx does where possible.
• Breathe v1.2.0
  • Change log not recorded.