You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Michael Jones e33d8e34eb Remove statements about 'reminding me' 1 year ago
.github/workflows CI: Update Sphinx versions tested against 1 year ago
breathe Fix typo 1 year ago
documentation Add example 1 year ago
examples Add example 1 year ago
requirements Add flake8 dependency & fix errors 1 year ago
tests Rename directive module to directives 1 year ago
.gitignore example.tag get modified during build, so .gitignore. 2 years ago
.readthedocs.yaml rtd: rework in attempt to fix builds 2 years ago
CHANGELOG.rst Add bold to breathe version numbers 1 year ago
CONTRIBUTING.rst Remove statements about 'reminding me' 1 year ago
LICENSE Rename license file 7 years ago
Makefile Rename directive module to directives 1 year ago
README.rst Remove statements about 'reminding me' 1 year ago Fix main arguments 7 years ago
mkrelease add mkrelease utility for mostly automated releasing 1 year ago
mypy.ini Add type-checking via mypy 2 years ago
setup.cfg Add license file to distribution 3 years ago Remove stale six dep 1 year ago



Packagers: Breathe packages on PyPI are PGP signed for Breathe >= v4.28.0.

Packagers: Breathe tarballs on GitHub are PGP signed for Breathe >= v4.29.0.


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


Breathe is available from github and PyPI, the Python Package Index. It can be installed with:

pip install breathe


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.


The testsuite can be run with:

make dev-test

The documentation also does a good effort of covering the available functionality with different examples. To build the documentation, run:


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


Further to this if you want to compare the current documentation output against a previous state in order to check for regressions there is a compare script in the documentation folder. It takes two arguments which are two commit references that you'd like to compare. This means that all your changes have to be committed first. Also the script does not resolve state dependent references like HEAD so provide concrete commit references like sha1s or branch names. A typical example is to compare your current branch output to master:

# Make sure all your changes are committed first
cd documentation
./compare master my-branch

This will do a checkout and build at each commit and then run meld against the resulting directories so you can see the differences introduced by your branch.


Development is currently done with:

  • Python 3.5
  • Docutils 0.12
  • Sphinx 2.3.1
  • 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 Archives

The archive for the Google groups list can be found here.

The previous mailing list was on and the archives are available here.

Please post new questions as GitHub issues.


Examples of Breathe used by other projects:

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


Breathe is not the only solution to this problem. These are the alternatives that we know about. We are very happy to list others if you'd like to provide a link in a GitHub issue.


See the mkrelease utility in the root of the repository.


Breathe is currently maintained by vermeeren and was formerly maintained by michaeljones & vitaut, contributors include:

Thanks to:

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


See the CHANGELOG.rst