Quick Start
===========

For this quick start we assume the following prerequisites:

* breathe was downloaded and extracted somewhere
* doxygen was installed and doxygen output (XML format) was generated for the
  project that is to be documented (set GENERATE_XML tag to YES)

We assume the following paths:

* documentation root path: :file:`/home/me/docproj/`
* breathe path: :file:`/home/me/docproj/ext/breathe/`
* doxygen xml output: :file:`/home/me/docproj/doxyxml/`

The documentation path should contain a folder :file:`source` containing the
:file:`conf.py` file. The doxygen xml output folder should contain the 
:file:`index.xml` output file generated by doxygen.

The following steps are required to integrate breathe functionality:

#. Add the breathe path to your conf.py by adding the following line::

    sys.path.append( "/home/me/docproj/ext/breathe/" )

#. Add breathe as an extension the line could look like this::

    extensions = ['sphinx.ext.pngmath', 'sphinx.ext.todo', 'breathe' ]

#. Tell breathe about the projects::

    breathe_projects = { "myproject": "/home/me/docproj/doxyxml/" }

#. Specify a default project::

    breathe_default_project = "myproject"

Once this is done you may use the following commands::

  .. doxygenindex::
  .. doxygenfunction::
  .. doxygenstruct::
  .. doxygenenum::
  .. doxygentypedef::
  .. doxygenclass::

to include documentation for different constructs. For each of these commands the
the following directives may be specified:

``project``
   Specifies which project, as defined in the breathe_projects config value,
   should be used for this directive. This overrides the default.

``path``
   Directly specifies the path to the folder with the doxygen output. This
   overrides the project and default project.