wiki:pjsip-doc/breathe

Version 3 (modified by bennylp, 10 years ago) (diff)

--

Generating This Documentation

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

Rendering The Documentation

The main source of the documentation is currently the '''Trac''' pages at https://trac.pjsip.org/repos/wiki/pjsip-doc/index. The copies in SVN are just copies for backup.

To render the documentation as HTML in _build/html directory:

$ cd $PJDIR/doc/pjsip-book
$ python fetch_trac.py
$ make

To build PDF, run:

$ make latexpdf

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>`_
?
.. default-domain:: cpp

will be rendered like this:

This is how to quote a code with syntax coloring:

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

There are many ways to refer a symbol:

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