Doxygen Integration with Breathe
================================
People say that the best way to use C++ with Sphinx is with Breathe. It seems to work, with some limitations though.

Requirements
------------

1. Sphinx: http://sphinx-doc.org. I installed with PyPI::
   
   $ sudo pip install sphinx
2. Breathe: http://michaeljones.github.io/breathe/index.html. I installed with PyPI::
   
   $ sudo pip install breathe
   
3. Doxygen. I installed from Ubuntu package.
4. Some say Pygments are needed for syntax coloring. I didn't remember installing it, maybe it was preinstalled, and I have no problem 
   with syntax coloring (see demo below).


Setup
-----
The emailed a tarball containing the pjsip-book source files with Doxygen integration. HTML output has already been generated for sample. 
Put this in `$PJ_DIR/doc` so that it becomes `$PJDIR/doc/pjsip-book`. Then just run make::

  $ make
  
This will build HTML documentation in `_build/html` directory. T build PDF, run::

  $ make latexpdf


.. default-domain:: cpp

How to Use Integrate Book with Doxygen
--------------------------------------
Quick sample::

  will be rendered like this:
  +++++++++++++++++++++++++++

  This is how to quote a code with syntax coloring:

  .. code-block:: c++

       pj::AudioMediaPlayer *player = new AudioMediaPlayer;
       player->createPlayer("announcement.wav");

  There are many ways to refer a symbol: 

  * A method: :cpp:func:`pj::AudioMediaPlayer::createPlayer()`
  * A method with alternate display: :cpp:func:`a method <pj::AudioMediaPlayer::createPlayer()>`
  * A class :cpp:class:`pj::AudioMediaPlayer`
  * A class with alternate display: :cpp:class:`a class <pj::AudioMediaPlayer>`

  For that links to work, we need to display the link target declaration (a class or method) 
  somewhere in the doc, like this:
  
  .. doxygenclass:: pj::AudioMediaPlayer
        :path: xml
        :members:

  Alternatively we can display a single method declaration like this:

  .. doxygenfunction:: pj::AudioMediaPlayer::createPlayer()
        :path: xml
        :no-link:

  We can also display class declaration with specific members.
  
  For more info see `Breathe documentation <http://michaeljones.github.io/breathe/domains.html>`_

     

will be rendered like this:
+++++++++++++++++++++++++++

This is how to quote a code with syntax coloring:

.. code-block:: c++

       pj::AudioMediaPlayer *player = new AudioMediaPlayer;
       player->createPlayer("announcement.wav");

There are many ways to refer a symbol: 

* A method: :cpp:func:`pj::AudioMediaPlayer::createPlayer()`
* A method with alternate display: :cpp:func:`a method <pj::AudioMediaPlayer::createPlayer()>`
* A class :cpp:class:`pj::AudioMediaPlayer`
* A class with alternate display: :cpp:class:`a class <pj::AudioMediaPlayer>`

For that links to work, we need to display the link target declaration (a class or method) somewhere in the doc, like this:
  
   .. doxygenclass:: pj::AudioMediaPlayer
        :path: xml
        :members:

Alternatively we can display a single method declaration like this:

   .. doxygenfunction:: pj::AudioMediaPlayer::createPlayer()
        :path: xml
        :no-link:

We can also display class declaration with specific members.

For more info see `Breathe documentation <http://michaeljones.github.io/breathe/domains.html>`_