.. BreatheExample documentation master file, created by sphinx-quickstart on Tue Feb  3 18:20:48 2009.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

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.

Features
--------

* **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 refence them by name or path for each directive.
* **Allows embedded restructured text in doxygen markup** - some extra doxygen
  aliases allow you to add ``\rst`` - ``\endrst`` blocks to your comments and have
  the contents interpreted as restructured text.
* **Plays well with Sphinx domains** - Link to entries in the breathe output with
  standard Sphinx domain references, like, ``:c:func:<my_function>``.

Contents
--------

.. toctree::
   :maxdepth: 1

   quickstart
   directives
   contributing
   codeguide
   testpages
   credits

In a Nutshell
-------------

You write code that looks a little like this:

.. literalinclude:: nutshell.h
   :language: cpp

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

With a ``conf.py`` setting like this::

   breathe_projects = {
       "nutshell":"../examples/specific/nutshell/xml/",
       }

And you get something like this:

----

   .. doxygenclass:: Nutshell
      :project: nutshell

----

Sound reasonable? To get started, go checkout the :doc:`quickstart guide <quickstart>`.

