Re #1715: updated book with latest Rst

git-svn-id: https://svn.pjsip.org/repos/pjproject/trunk@4763 74dad513-b988-da41-8d7b-12977e46ad98

Author: bennylp

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>`_
+
+
+

doc/pjsip-book/conf.py

@@ -40,8 +40,8 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'The PJSIP Book'
-copyright = u'2013, Teluu Ltd.'
+project = u'PJSUA2 Documentation'
+copyright = u'2014, Teluu Ltd.'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -50,7 +50,7 @@
 # The short X.Y version.
 version = '1.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.0-beta'
+release = '1.0-alpha'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -164,7 +164,7 @@
 #html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'ThePJSIPBookdoc'
+htmlhelp_basename = 'PJSUA2Doc'
 
 
 # -- Options for LaTeX output --------------------------------------------------
@@ -183,7 +183,7 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'ThePJSIPBook.tex', u'The PJSIP Book Documentation',
+  ('index', 'PJSUA2Doc.tex', u'PJSUA2 Documentation',
    u'Sauw Ming Liong, Benny Prijono', 'manual'),
 ]
 
@@ -213,7 +213,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'thepjsipbook', u'The PJSIP Book Documentation',
+    ('index', 'pjsua2doc', u'PJSUA2 Documentation',
      [u'Sauw Ming Liong', u'Benny Prijono'], 1)
 ]
 
@@ -227,7 +227,7 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'ThePJSIPBook', u'The PJSIP Book Documentation',
+  ('index', 'PJSUA2Doc', u'PJSUA2 Documentation',
    u'Sauw Ming Liong@*Benny Prijono', 'ThePJSIPBook', 'One line description of project.',
    'Miscellaneous'),
 ]