docs: Updating documentation for 0.1.0 release
Change-Id: I1834a8a2ba9a9c7059517e3dbd784a377b0457bd
Refs: #1583
diff --git a/README.md b/README.md
index 6b48521..c7cdfa5 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@
* [ChronoChat - Multi-user NDN chat application](https://github.com/named-data/ChronoChat)
* [ChronoSync - Sync library for multiuser realtime applications for NDN](https://github.com/named-data/ChronoSync)
* [ndn-tlv-ping - Ping Application For NDN](https://github.com/named-data/ndn-tlv-ping)
-* [ndn-traffic - Traffic Generator For NDN](https://github.com/named-data/ndn-traffic)
+* [ndn-traffic-generator - Traffic Generator For NDN](https://github.com/named-data/ndn-traffic-generator)
See the file [`docs/INSTALL.rst`](https://github.com/cawka/ndn-cxx/blob/master/docs/INSTALL.rst)
for build and install instructions.
diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst
index 19ef042..e61cf24 100644
--- a/docs/INSTALL.rst
+++ b/docs/INSTALL.rst
@@ -77,23 +77,30 @@
- ``doxygen``
- ``graphviz``
-- ``python-sphinx``
+- ``python-sphinx`` and sphinx extensions ``sphinxcontrib-doxylink``,
+ ``sphinxcontrib-googleanalytics``
-The following lists steps for common platforms to install these
-prerequisites:
+The following lists steps for common platforms to install these prerequisites:
- On OS X 10.8 and 10.9 with MacPorts::
sudo port install doxygen graphviz py27-sphinx sphinx_select
sudo port select sphinx py27-sphinx
+ # Install sphinx extensions
+ sudo port install py27-pip
+ sudo port select pip pip27
+ sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
+
- On Ubuntu >= 12.04::
- sudo apt-get install doxygen graphviz python-sphinx
+ sudo apt-get install doxygen graphviz python-sphinx python-pip
+ sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
- On Fedora >= 20::
sudp yum install doxygen graphviz python-sphinx
+ sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
Build
-----
@@ -132,6 +139,21 @@
- ``build/unit-tests``: A unit test binary for the library
+Debug symbols
+~~~~~~~~~~~~~
+
+The default compiler flags enable debug symbols to be included in binaries (i.e., ``-g``
+flag for ``./waf configure`` and ``-g3`` for ``./waf configure --debug``). This
+potentially allows more meaningful debugging information if your application crashes.
+
+If it is undesirable, default flags can be easily overridden:
+
+::
+
+ CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
+ ./waf
+ sudo ./waf install
+
Documentation
-------------
diff --git a/docs/README.rst b/docs/README.rst
new file mode 100644
index 0000000..60fc7ed
--- /dev/null
+++ b/docs/README.rst
@@ -0,0 +1,25 @@
+ndn-cxx overview
+================
+
+ndn-cxx is a C++ library, implementing Named Data Networking (NDN) primitives that can be
+used to implement various NDN applications. The library is currently being used as part of
+the following projects:
+
+- `NFD - NDN Forwarding Daemon <http://named-data.net/doc/NFD>`__
+- `NLSR - Named-data Link-State Routing
+ protocol <https://github.com/named-data/NLSR>`__
+- `repo-ng - Next generation of NDN
+ repository <https://github.com/named-data/repo-ng>`__
+- `ChronoChat - Multi-user NDN chat
+ application <https://github.com/named-data/ChronoChat>`__
+- `ChronoSync - Sync library for multiuser realtime applications for
+ NDN <https://github.com/named-data/ChronoSync>`__
+- `ndn-tlv-ping - Ping Application For
+ NDN <https://github.com/named-data/ndn-tlv-ping>`__
+- `ndn-traffic-generator - Traffic Generator For
+ NDN <https://github.com/named-data/ndn-traffic-generator>`__
+
+Please submit any bugs or issues to the `ndn-cxx issue tracker
+<http://redmine.named-data.net/projects/ndn-cxx/issues>`__.
+
+.. include:: RELEASE_NOTES.rst
diff --git a/docs/RELEASE_NOTES.rst b/docs/RELEASE_NOTES.rst
index 886ca98..b6113af 100644
--- a/docs/RELEASE_NOTES.rst
+++ b/docs/RELEASE_NOTES.rst
@@ -1,7 +1,7 @@
.. _ndn-cxx v0.1.0 Release Notes:
ndn-cxx v0.1.0 Release Notes
-============================
+----------------------------
Version 0.1.0 is the initial release of ndn-cxx, an NDN C++ library with eXperimental
eXtensions.
diff --git a/docs/conf.py b/docs/conf.py
index 132c961..8131fcb 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -33,6 +33,23 @@
'sphinx.ext.todo',
]
+def addExtensionIfExists(extension):
+ try:
+ __import__(extension)
+ extensions.append(extension)
+ except ImportError, e:
+ print e
+ sys.stderr.write("Extension '%s' in not available. "
+ "Some documentation may not build correctly.\n" % extension)
+ sys.stderr.write("To install, use \n"
+ " sudo pip install %s\n" % extension.replace('.', '-'))
+ pass
+
+addExtensionIfExists('sphinxcontrib.doxylink')
+
+if os.getenv('GOOGLE_ANALYTICS', None):
+ addExtensionIfExists('sphinxcontrib.googleanalytics')
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -243,3 +260,16 @@
# If true, show URL addresses after external links.
man_show_urls = True
+
+
+# ---- Custom options --------
+
+doxylink = {
+ 'ndn-cxx' : ('ndn-cxx.tag', 'doxygen/'),
+}
+
+if os.getenv('GOOGLE_ANALYTICS', None):
+ googleanalytics_id = os.environ['GOOGLE_ANALYTICS']
+ googleanalytics_enabled = True
+
+exclude_patterns = ['RELEASE_NOTES.rst']
diff --git a/docs/doxygen.conf.in b/docs/doxygen.conf.in
index a25b2ec..24b3de7 100644
--- a/docs/doxygen.conf.in
+++ b/docs/doxygen.conf.in
@@ -1035,7 +1035,7 @@
# that doxygen normally uses.
# This tag requires that the tag GENERATE_HTML is set to YES.
-HTML_FOOTER = ../docs/named_data_theme/named_data_footer.html
+HTML_FOOTER = @HTML_FOOTER@
# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style
# sheet that is used by each HTML page. It can be used to fine-tune the look of
@@ -1972,7 +1972,7 @@
# tag file that is based on the input files it reads. See section "Linking to
# external documentation" for more information about the usage of tag files.
-GENERATE_TAGFILE =
+GENERATE_TAGFILE = ndn-cxx.tag
# If the ALLEXTERNALS tag is set to YES all external class will be listed in the
# class index. If set to NO only the inherited external classes will be listed.
diff --git a/docs/examples.rst b/docs/examples.rst
index a78420d..793cd89 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -1,13 +1,18 @@
-Basic examples
-==============
+Trivial applications
+====================
Trivial consumer
----------------
-In the following trivial example, a consumer creates a Face with default transport (UnixSocket transport) and sends an Interest for ``/localhost/testApp/randomData``.
-While expressing Interest, the app specifies two callbacks to be called when Data is retrieved or Interest times out.
+In the following trivial example, a consumer creates a :ndn-cxx:`Face` with default
+transport (:ndn-cxx:`UnixTransport`) and sends an Interest for
+``/localhost/testApp/randomData``. While expressing Interest, the app specifies two
+callbacks to be called when Data is retrieved or Interest times out.
-``ndn::bind`` is an alias for either `boost::bind <http://www.boost.org/doc/libs/1_55_0/libs/bind/bind.html>`_ or `std::bind <http://en.cppreference.com/w/cpp/utility/functional/bind>`_ when the library is compiled in C++11 mode.
+``ndn::bind`` is an alias for either `boost::bind
+<http://www.boost.org/doc/libs/1_55_0/libs/bind/bind.html>`_ or `std::bind
+<http://en.cppreference.com/w/cpp/utility/functional/bind>`_ when the library is compiled
+in C++11 mode.
.. literalinclude:: ../examples/consumer.cpp
:language: c++
@@ -20,14 +25,18 @@
The following example demonstrates how to write a simple producer application.
-First, application sets interset filter for ``/localhost/testApp`` to receive all Interests that have this prefix.
-``setInterestFilter`` call accepts two callbacks, one which will be called when an Interest is received, and the other if prefix registration (i.e., configuring proper FIB entry in NFD) fails.
+First, the application sets an Interset filter for ``/localhost/testApp`` to receive all
+Interests that have this prefix. The :ndn-cxx:`Face::setInterestFilter` call accepts two
+callbacks; the first will be called when an Interest is received and the second if prefix
+registration fails.
-After Interest is received, a producer creates a Data packet with the same name as in the received Interest, adds a silly content, and signs the Data packet with the system-default identity.
-It is possible to specify a particular key to be used during the signing.
-For more information, refer to KeyChain API documentation.
+After an Interest is received, the producer creates a Data packet with the same name as
+the received Interest, adds content, and signs it with the system-default identity. It is
+also possible to specify a particular key to be used during the signing. For more
+information, refer to :ndn-cxx:`KeyChain API documentation <KeyChain>`.
-Finally, after Data packet has been created and signed, it is returned to the requester using ``Face::put`` method.
+Finally, after Data packet has been created and signed, it is returned to the requester
+using :ndn-cxx:`Face::put` method.
.. literalinclude:: ../examples/producer.cpp
:language: c++
@@ -38,13 +47,20 @@
Consumer that uses ndn::Scheduler
---------------------------------
-The following example demonstrates use for ``ndn::Scheduler`` to schedule an arbitrary events for execution at specific points of time.
+The following example demonstrates how to use :ndn-cxx:`ndn::Scheduler` to schedule arbitrary
+events for execution at specific points of time.
-The library internally uses `boost::asio::io_service <http://www.boost.org/doc/libs/1_48_0/doc/html/boost_asio/reference/io_service.html>`_ to implement fully asynchronous NDN operations (i.e., sending and receiving Interests and Data).
-In addition to network-related operations, ``boost::asio::io_service`` can be used to execute any arbitrary callback within the processing thread (run either explicitly via ``io->run`` or implicitly via ``Face::processEvents`` as in previous examples).
-``ndn::Scheduler`` is just a wrapper on top of ``boost::asio::io_service``, allowing simple interface to schedule tasks at specific times.
+The library internally uses `boost::asio::io_service
+<http://www.boost.org/doc/libs/1_48_0/doc/html/boost_asio/reference/io_service.html>`_ to
+implement fully asynchronous NDN operations (i.e., sending and receiving Interests and
+Data). In addition to network-related operations, ``boost::asio::io_service`` can be used
+to execute any arbitrary callback within the processing thread (run either explicitly via
+``io.run`` or implicitly via :ndn-cxx:`Face::processEvents` as in previous examples).
+:ndn-cxx:`ndn::Scheduler` is just a wrapper on top of ``boost::asio::io_service``,
+allowing simple interface to schedule tasks at specific times.
-The highlighted lines in the example demonstrate all that is needed to express a second interest approximately 2 seconds after the first one.
+The highlighted lines in the example demonstrate all that is needed to express a second
+Interest approximately 2 seconds after the first one.
.. literalinclude:: ../examples/consumer-with-timer.cpp
:language: c++
diff --git a/docs/index.rst b/docs/index.rst
index 9cd0035..2cbeb1d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -2,22 +2,7 @@
=====================================================
ndn-cxx is a C++ library, implementing Named Data Networking (NDN) primitives that can be
-used to implement various NDN applications. The library is currently being used as part of
-the following projects:
-
-- `NFD - NDN Forwarding Daemon <https://github.com/named-data/NFD>`__
-- `NLSR - Named-data Link-State Routing
- protocol <https://github.com/named-data/NLSR>`__
-- `repo-ng - Next generation of NDN
- repository <https://github.com/named-data/repo-ng>`__
-- `ChronoChat - Multi-user NDN chat
- application <https://github.com/named-data/ChronoChat>`__
-- `ChronoSync - Sync library for multiuser realtime applications for
- NDN <https://github.com/named-data/ChronoSync>`__
-- `ndn-tlv-ping - Ping Application For
- NDN <https://github.com/named-data/ndn-tlv-ping>`__
-- `ndn-traffic - Traffic Generator For
- NDN <https://github.com/named-data/ndn-traffic>`__
+used to implement various NDN applications.
Please submit any bugs or issues to the `ndn-cxx issue tracker
<http://redmine.named-data.net/projects/ndn-cxx/issues>`__.
@@ -25,39 +10,34 @@
ndn-cxx Documentation
---------------------
-
.. toctree::
:hidden:
- :maxdepth: 2
+ :maxdepth: 3
- RELEASE_NOTES
+ README
INSTALL
examples
- tutorials/security-library
- tutorials/utils-ndn-regex
- tutorials/security-validator-config
- manpages
+ tutorials
code-style
+- :doc:`README`
+
+- :doc:`INSTALL`
+
+- :doc:`examples`
+
+- :doc:`tutorials`
+
+ + :doc:`tutorials/security-library`
+ + :doc:`tutorials/utils-ndn-regex`
+ + :doc:`tutorials/security-validator-config`
+ + :doc:`manpages`
+
+Documentation for ndn-cxx developers and contributors
++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
- `API documentation (doxygen) <doxygen/annotated.html>`_
-- :doc:`ndn-cxx v0.1.0 Release Notes <RELEASE_NOTES>`
-
-- :doc:`Getting Started with ndn-cxx <INSTALL>`
-
-- :doc:`Tutorial Examples <examples>`
-
-- :doc:`tutorials/security-library`
-
-- :doc:`tutorials/utils-ndn-regex`
-
-- :doc:`tutorials/security-validator-config`
-
-- :doc:`manpages`
-
-Documentation for ndn-cxx contributors
-++++++++++++++++++++++++++++++++++++++
-
- :doc:`code-style`
License
diff --git a/docs/named_data_theme/layout.html b/docs/named_data_theme/layout.html
index 9f186e4..78b6477 100644
--- a/docs/named_data_theme/layout.html
+++ b/docs/named_data_theme/layout.html
@@ -36,11 +36,13 @@
<div class="sidebar">
{%- block sidebartoc %}
<h3>{{ _('Table Of Contents') }}</h3>
+ {{ toctree(includehidden=True) }}
+
+ <h3>{{ _('Developer documentation') }}</h3>
<ul>
<li class="toctree-l1"><a class="reference internal" href="doxygen/annotated.html">API documentation (doxygen)</a></li>
+ <li class="toctree-l1"><a class="reference internal" href="code-style.html">ndn-cxx Code Style and Coding Guidelines</a></li>
</ul>
-
- {{ toctree(includehidden=True) }}
{%- endblock %}
{%- block sidebarsearch %}
@@ -78,17 +80,6 @@
</div>
</div>
</div><!--footer info end-->
-
- <script type="text/javascript">
- var _gaq = _gaq || [];
- _gaq.push(['_setAccount', 'UA-22320603-1']);
- _gaq.push(['_trackPageview']);
- (function() {
- var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
- ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
- var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
- })();
- </script>
{% endblock %}
{% block relbar1 %}{% endblock %}
diff --git a/docs/named_data_theme/named_data_footer-with-analytics.html.in b/docs/named_data_theme/named_data_footer-with-analytics.html.in
new file mode 100644
index 0000000..b05c1f2
--- /dev/null
+++ b/docs/named_data_theme/named_data_footer-with-analytics.html.in
@@ -0,0 +1,37 @@
+<!-- start footer part -->
+<!--BEGIN GENERATE_TREEVIEW-->
+<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
+ <ul>
+ $navpath
+ <li class="footer">$generatedby
+ <a href="http://www.doxygen.org/index.html">
+ <img class="footer" src="$relpath$doxygen.png" alt="doxygen"/></a> $doxygenversion </li>
+ </ul>
+</div>
+<!--END GENERATE_TREEVIEW-->
+<!--BEGIN !GENERATE_TREEVIEW-->
+<hr class="footer"/>
+<address class="footer"><small>
+$generatedby  <a href="http://www.doxygen.org/index.html">
+<img class="footer" src="$relpath$doxygen.png" alt="doxygen"/>
+</a> $doxygenversion
+</small></address>
+<!--END !GENERATE_TREEVIEW-->
+
+<script type="text/javascript">
+
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', '@GOOGLE_ANALYTICS@']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+</script>
+
+<script type="text/javascript">
+</script>
+</body>
+</html>
diff --git a/docs/named_data_theme/static/named_data_style.css_t b/docs/named_data_theme/static/named_data_style.css_t
index c1f02f9..3edfb72 100644
--- a/docs/named_data_theme/static/named_data_style.css_t
+++ b/docs/named_data_theme/static/named_data_style.css_t
@@ -38,10 +38,10 @@
margin-bottom: 18px;
}
-h1 { font-weight: normal; font-size: 24px; }
-h2 { font-weight: normal; font-size: 18px; }
-h3 { font-weight: bold; font-size: 18px; }
-h4 { font-weight: normal; font-size: 18px; }
+h1 { font-weight: bold; font-size: 24px; }
+h2 { font-weight: bold; font-size: 18px; }
+h3 { font-weight: bold; font-size: 16px; }
+h4 { font-weight: bold; font-size: 14px; }
hr {
background-color: #c6c6c6;
diff --git a/docs/tutorials.rst b/docs/tutorials.rst
new file mode 100644
index 0000000..1195ce6
--- /dev/null
+++ b/docs/tutorials.rst
@@ -0,0 +1,10 @@
+Tutorials
+=========
+
+.. toctree::
+ :maxdepth: 2
+
+ tutorials/security-library
+ tutorials/utils-ndn-regex
+ tutorials/security-validator-config
+ manpages
diff --git a/wscript b/wscript
index 1ccfc88..175ea12 100644
--- a/wscript
+++ b/wscript
@@ -206,9 +206,15 @@
else:
bld(features="subst",
name="doxygen-conf",
- source="docs/doxygen.conf.in",
- target="docs/doxygen.conf",
+ source=["docs/doxygen.conf.in",
+ "docs/named_data_theme/named_data_footer-with-analytics.html.in"],
+ target=["docs/doxygen.conf",
+ "docs/named_data_theme/named_data_footer-with-analytics.html"],
VERSION=VERSION,
+ HTML_FOOTER="../build/docs/named_data_theme/named_data_footer-with-analytics.html" \
+ if os.getenv('GOOGLE_ANALYTICS', None) \
+ else "../docs/named_data_theme/named_data_footer.html",
+ GOOGLE_ANALYTICS=os.getenv('GOOGLE_ANALYTICS', ""),
)
bld(features="doxygen",