michaeljones/ breathe

(v4.31.0) 3 months ago

Python

Shell

doxygen

sphinx

View on GitHub

Need help with breathe?

Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

michaeljones

561 Stars

152 Forks

Other

1.6K Commits

120 Opened issues

Description

ReStructuredText and Sphinx bridge to Doxygen

Services available

Need anything else?

Contributors list

Readme

Breathe

Name: breathe
Brand: breathe
SKU: //michaeljones/breathe
Rating: 3.122 (561 reviews)

.. image:: https://github.com/michaeljones/breathe/workflows/unit%20tests/badge.svg :target: https://github.com/michaeljones/breathe/actions?query=workflow%3A%22unit+tests%22

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

Install

Breathe is available from github and

PyPI, the Python Package Index

_. It can be installed with::

pip install breathe

Packagers ~~~~~~~~~

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

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

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

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::

make

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

documentation/build/html/index.html

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.

Requirements

Breathe requires Python 3.6+, Sphinx 3.0+ and Doxygen 1.8+.

Mailing List Archives

The archive for the Google groups list can be found

here

__.

The previous mailing list was on

librelist.com

__ and the archives are available

here

__.

Please post new questions as GitHub issues.

Examples

Examples of Breathe used by other projects:

```
fmt 
```
_
```
Lasso C API 
```
_ [
```
pdf 
```
__]

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

Alternatives

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.

```
Gasp 
```
_
```
Robin 
```
_
```
sphinxcontrib-autodoc_doxygen 
```
_

Release

See the

mkrelease

utility in the root of the repository.

Useful vim command for changelog conversion to the git tag format:

%s/\v`(#[0-9]+) \.

Credits

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

```
nijel 
```
_
```
sebastianschaetz 
```
_
```
mbolivar 
```
_
```
queezythegreat 
```
_
```
abingham 
```
_
```
davidm 
```
_
```
hobu 
```
_
```
magro11 
```
_
```
scopatz 
```
_
```
vonj 
```
_
```
jmnas 
```
_
```
donkopotamus 
```
_
```
jo3w4rd 
```
_
```
Anthony Truchet 
```
_
```
Daniel Matz 
```
_
```
Andrew Hundt 
```
_
```
sebastinas 
```
_
```
robo9k 
```
_
```
sieben 
```
_
```
rweickelt 
```
_
```
sam-roth 
```
_
```
bnewbold 
```
_
```
serge-sans-paille 
```
_
```
dean0x7d 
```
_
```
Andne 
```
_
```
Tiwalun 
```
_
```
eric-wieser 
```
_
```
olitheolix 
```
_
Many more, this list is rather outdated. Refer to the git history.

Thanks to:

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

Changelog

See the

CHANGELOG.rst