Changes between Initial Version and Version 1 of pjsip-doc/breathe

Timestamp:

Dec 4, 2013 3:29:37 AM (10 years ago)

Author:

bennylp

Comment:

--

pjsip-doc/breathe

@@ +1 @@
+{{{
+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>`_
+
+
+
+}}}