Quickstart
==========

For this quickstart 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 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.