diff options
Diffstat (limited to 'doc/pjsip-book/breathe.rst')
-rw-r--r-- | doc/pjsip-book/breathe.rst | 113 |
1 files changed, 113 insertions, 0 deletions
diff --git a/doc/pjsip-book/breathe.rst b/doc/pjsip-book/breathe.rst new file mode 100644 index 00000000..ea6d3516 --- /dev/null +++ b/doc/pjsip-book/breathe.rst @@ -0,0 +1,113 @@ +Appendix: Generating This Documentation +======================================= + +Requirements +------------ + +This documentation is created with `Sphinx <http://sphinx-doc.org>`_ and `Breathe <http://michaeljones.github.io/breathe/index.html>`_. Here are the required tools: + +1. Doxygen is required. `Install <http://www.stack.nl/~dimitri/doxygen/download.html#srcbin>`_ it for your platform. + +2. The easiest way to install all the tools is with `Python Package Index (PyPI) <http://pypi.python.org>`_. Just run this and it will install Sphinx, Breathe, and all the required tools if they are not installed:: + + $ sudo pip install breathe + +3. Otherwise if PyPI is not available, consult Sphinx and Breathe sites for installation instructions and you may need to install these manually: + + - `Sphinx <http://sphinx-doc.org>`_ + - `Breathe <http://michaeljones.github.io/breathe/index.html>`_ + - docutils + - Pygments + + +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: + +.. 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>`_ + + + |