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.
 
 
 
 
Melvin Vermeeren f1e22cb871
rtd: move pip dependencies to conda environment
1 day ago
.github/workflows documentation overhaul (#816) 2 weeks ago
breathe version: release v4.34.0 2 weeks ago
documentation rtd: move pip dependencies to conda environment 1 day ago
examples documentation overhaul (#816) 2 weeks ago
requirements doc: switch to furo theme 1 day ago
scripts Format files 5 months ago
tests Format all files with pinned black version 5 months ago
.gitignore convert relative path to absolute 4 months ago
.readthedocs.yaml rtd: move pip dependencies to conda environment 1 day ago
CHANGELOG.rst version: release v4.34.0 2 weeks ago
CONTRIBUTING.rst Remove statements about 'reminding me' 10 months ago
CONTRIBUTORS.rst Use generated list of contributors 6 months ago
LICENSE Rename license file 7 years ago
Makefile Set PYTHONPATH for version check 5 months ago
README.rst Bump Sphinx requirement to >=4,<6 (from >=3,<5) 2 months ago
breathe-apidoc.py Auto format all python files with black 9 months ago
mkrelease add mkrelease utility for mostly automated releasing 1 year ago
mypy.ini Add type-checking via mypy 2 years ago
pyproject.toml Add pyproject.toml 9 months ago
setup.cfg Switch to per-file-ignores in config 9 months ago
setup.py version: release v4.34.0 2 weeks ago

README.rst

Breathe

Your technical docs, beautifully integrated

WebsiteDocumentationSponsor

Sponsor: If you benefit from using Breathe as a company or an individual, you can financially support the Breathe project with recurring or one off contributions via Open Collective.


Breathe is a Sphinx plugin providing beautifully integrated Doxygen output in your user-facing documentation. It allows you to combine Doxygen's excellent technical understanding of your code base with the superb long form documentation output of the Sphinx system.

For 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.

Download

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

pip install breathe

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 4.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.

Projects Using Breathe

Examples of projects that use Breathe:

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]+) \<[^`]*`__/\1/g.

Maintainers

Breathe is currently maintained by vermeeren & jakobandersen and was formerly maintained by michaeljones & vitaut.

See CONTRIBUTORS for the full list.

Acknowledgements

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

Changelog

See the CHANGELOG.rst