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.

Warning

This documentation is built from the latest Breathe github project code. It does not necessarily reflect a released version of Breathe on PyPI.

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 - \endrst blocks 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

enum Tool#

Our tool set.

The various tools we can opt to use to crack this particular nut

Values:

enumerator kHammer#

What? It does the job.

enumerator kNutCrackers#

Boring.

enumerator kNinjaThrowingStars#

Stealthy.

Public Functions

Nutshell()#

Nutshell constructor.

~Nutshell()#

Nutshell destructor.

void crack(Tool tool)#

Crack that shell with specified tool

Parameters:

tool – the tool with which to crack the nut

bool isCracked()#
Returns:

Whether or not the nut is cracked


Sound reasonable? To get started, go checkout the quickstart guide.