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


.. ifconfig:: documentation_build == 'readthedocs_latest'

   .. warning::

      This documentation is built from the latest `Breathe github project
      <https://github.com/michaeljones/breathe>`_ code. It does not necessarily
      reflect a released version of Breathe on PyPI.

.. ifconfig:: documentation_build == 'development'

   .. warning::

      This build of the documentation is not from a specific tagged release of
      Breathe. It reflects a work in progress state of Breathe. Please see the
      `github repository <https://github.com/michaeljones/breathe>`_ for a more
      official source of information.


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

.. toctree::
   :maxdepth: 1

   quickstart
   directives
   differences
   readthedocs

Features
--------

.. toctree::
   :maxdepth: 1

   markups
   latexmath
   codeblocks
   domains
   customcss
   groups
   lists
   tables
   template
   dot_graphs

Contributing
------------

.. toctree::
   :maxdepth: 1

   contributing
   codeguide
   credits

Example/Test Pages
------------------

.. toctree::
   :maxdepth: 1

   testpages

Download
--------

Breathe is available from:

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

License
-------

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

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:

----

.. cpp:namespace:: @ex_index

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

----

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