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 source for the documentation is in the
documentation folder if you want
to built it and read it locally.
Breathe does not always get the attention it deserves but I am keen to keep it moving forward. If you report an issue, please keep reminding me about it until it is fixed. I should be better at this but in silence I tend to move to other things so keep reminding me.
The testsuite can be run with:
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
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
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
the resulting directories so you can see the differences introduced by your
Development is currently done with:
- Python 2.7
- Docutils 0.11
- Sphinx 1.4
- 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.
There is a mailing list available on Google groups:
The mailing list is quieter than the Github repository so feel free to post 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 or get in touch on the mailing list.
Command for releasing source bundle & wheel to PyPI:
python setup.py sdist bdist_wheel upload
- Anthony Truchet
- Daniel Matz
- Andrew Hundt
- Dimitri van Heesch for Doxygen.
- Georg Brandl for Sphinx.
- David Goodger for Docutils and reStructuredText.
Inspired by Keepachangelog.com.
- 2017-02-25 - Breathe v4.6.0
- Support for the Interface directive
- Display the contents of defines
- 2017-02-12 - Breathe v4.5.0
- Improve handling of c typedefs
- Support new desc_signature_line node
- Add --project flag to breathe-apidoc helper
- Dropped testing for Python 3.3 and added 3.6
- 2016-11-13 - Breathe v4.4.0
- Improve single line parameter documentation rendering
- 2016-11-05 - Breathe v4.3.1
- Version bump package confusion with wheel release
- 2016-11-05 - Breathe v4.3.0
- Rewritten rendering approach to use the visitor pattern
- Dropped support for 2.6 & added testing for 3.5
- Issue with running breathe-apidoc for the first time.
- Improved handling of qualifiers, eg. const & volatile.
- Supports functions in structs
- Supports auto-doxygen code path on Windows
- 2016-03-19 - Breathe v4.2.0
- Output links to a class' parents & children.
- Support for Sphinx's needs_extensions config option.
- breathe-apidoc script for generating ReStructuredText stub files with Breathe directives from doxygen xml files.
- Handling default values in parameter declarations
- Output order not being reproducible due to iteration over Set.
- Handling of multiple pointers and references
- SEVERE: Duplicate ID warnings when using function overloads.
- Use project name for link references when using default project. So we use the project name instead of 'project0'.
- 2015-08-27 - Breathe v4.1.0
breathe_doxygen_config_optionsconfig variable which allows for adding more config lines to the doxygen file used for the auto-directives.
- Display of array & array reference parameters for functions.
- Handling of links to classes with template arguments.
- Handling of unnamed enums in C.
- Naming of template parameter section.
- Finding functions that are within groups.
- Rendering of 'typename' and 'class' keywords for templates.
- 2015-04-02 - Breathe v4.0.0
- Significant work on the code base with miminal reStructureText interface changes. To be documented.
- 2014-11-09 - Breathe v3.2.0
- Nothing Added, Deprecated or Removed
- Changed docutils/Sphinx node usage to fix latex/pdf output.
- When checking for path separators check for both
\regardless of the platform.
autodirectives without specifying the
:project:option even though the default project config setting was set.
- Use of
doxygenfunctionno longer inappropriately triggers the duplicate target check and fails to output link targets.
- Support for inline urls in the doxygen comments.
- Support for array notation in function parameters.
- Reduced intention by changing
rubricnodes rather than
descnodes with signatures & content. Now headings like 'Public Functions' appear inline with their subject matter.
- 2014-09-07 - Breathe v3.1.0
- Nothing Deprecated or Removed
doxygenclassdirective can now reference template specialisations by specifying the specialisation in the argument name.
- Displaying function parameters for Qt slots output. Previously they were missing even though Qt Slots are essentially just functions.
- Displaying headings from doxygen comments as emphasized text.
- Crash when generating warning about being unable to find a define, variable, enum, typedef or union.
- Only output the definition name for a function parameter if the declartion name is not available. Previously, where they were both available we were getting two names next to each other for no good reason.
- 2014-08-04 - Breathe v3.0.0
- Improve output of const, volatile, virtual and pure-virtual keywords.
- Fix css class output for HTML so that object types rather than names are output as the css classes. eg. 'function' instead of 'myFunction'.
- Fix issue with Breathe getting confused over functions appearing in header and implementation files.
- Improve matching for overloaded functions when using
doxygenfunctiondirective. Also, provide a list of potential matches when no match is found.
:members:implementation to handle inner classes properly.
doxygenstructto share the
doxygenclassimplementation path which grants it the options from
:outline:option support to
- Breaking change: Removed
doxygengroupdirectives and replaced it with
:private-members:, and changed
breathe_default_sectionsconfig variable to
breathe_default_members. This is designed to more closely match the Sphinx autodoc functionality and interface.
- 2014-06-15 - Breathe v2.0.0
- Add compare script for checking changes to documentation caused by changes in the implementation.
- Switched to
- Breaking change: Change
autodoxygen*directives to require explicitly declared source files in the
conf.pyrather 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.pyfile. Previously, it would assume they were relative to the user's current working directory. This breaks projects which use separate build & source directories.
- 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.