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

Contents
--------

.. toctree::
   :maxdepth: 1

   quickstart
   directives
   markups
   domains
   groups
   template
   contributing
   codeguide
   testpages
   credits

Download
--------

Breathe is available from:

* `PyPI, the Python Package Index <http://pypi.python.org/pypi/breathe>`_
* `Github <https://github.com/michaeljones/breathe>`_

Licence
-------

Breathe is under the `BSD licence
<https://github.com/michaeljones/breathe/blob/master/LICENCE>`_.

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

You write code that looks a little like this:

.. literalinclude:: code/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
      :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:

----

.. doxygenclass:: Nutshell
   :project: nutshell
   :members:

----

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

