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