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:

   .. code-block:: python

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

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

   .. code-block:: python

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

#. Tell breathe about the projects:

   .. code-block:: python

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

#. Specify a default project:

   .. code-block:: python

     breathe_default_project = "myproject"

Once this is done you may use the following commands to include documentation for different
constructs:

.. code-block:: rst

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

For each of these commands 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.
