Breathe’s documentation¶
Breathe provides a bridge between the Sphinx and Doxygen documentation systems.
It is an easy way to include Doxygen information in a set of documentation generated by Sphinx. The aim is to produce an autodoc like support for people who enjoy using Sphinx but work with languages other than Python. The system relies on the Doxygen’s xml output.
Overview¶
Simple setup - one doxygen config value, one Sphinx config value and one directive and you’ll be on your way.
High and low level directives - reference the whole project, just a class or just a function with different directives.
Support for multiple doxygen projects - set it up to be aware of different projects and reference them by name or path for each directive.
Allows embedded reStructuredText in doxygen markup - some extra doxygen aliases allow you to add
\rst-\endrstblocks to your comments and have the contents interpreted as reStructuredText.Basic support for Sphinx domains - Link to functions in the breathe output with a standard Sphinx domain reference.
Setup & Usage¶
Features¶
Contributing¶
Example/Test Pages¶
Download¶
Breathe is available from:
License¶
Breathe is under the BSD license.
In a Nutshell¶
You write code that looks a little like this:
/**
\file nutshell.h
An overly extended example of how to use breathe
*/
/*!
With a little bit of a elaboration, should you feel it necessary.
*/
class Nutshell
{
public:
//! Our tool set
/*! The various tools we can opt to use to crack this particular nut */
enum Tool
{
kHammer = 0, //!< What? It does the job
kNutCrackers, //!< Boring
kNinjaThrowingStars //!< Stealthy
};
//! Nutshell constructor
Nutshell();
//! Nutshell destructor
~Nutshell();
/*! Crack that shell with specified tool
\param tool - the tool with which to crack the nut
*/
void crack( Tool tool );
/*!
\return Whether or not the nut is cracked
*/
bool isCracked();
private:
//! Our cracked state
bool m_isCracked;
};
Then you run this:
doxygen
With a setting that says this:
GENERATE_XML = YES
Then in your Sphinx documentation, you add something like this:
.. doxygenclass:: Nutshell
:project: nutshell
:members:
With a conf.py setting like this:
breathe_projects = {
"nutshell":"../../examples/specific/nutshell/xml/",
}
And Breathe registered as an extension in conf.py like this:
extensions = [ "breathe" ]
You get something like this:
-
class Nutshell¶
With a little bit of a elaboration, should you feel it necessary.
Public Types
Sound reasonable? To get started, go checkout the quickstart guide.