docs: Documentation updates
Change-Id: I7e10ba6bd1f70e779d5c2fc0437ff0f15828b312
Refs: #1923
diff --git a/docs/GETTING-STARTED.rst b/docs/GETTING-STARTED.rst
index 4dd6d1d..216677f 100644
--- a/docs/GETTING-STARTED.rst
+++ b/docs/GETTING-STARTED.rst
@@ -7,7 +7,7 @@
Getting Source
--------------
-- `Github NLSR repository <https://github.com/named-data/NLSR>`_
+- `GitHub NLSR repository <https://github.com/named-data/NLSR>`_
Installation
------------
@@ -18,11 +18,9 @@
-------------
After installing NLSR from source, you need to create a configuration file for
-NLSR. Please take a look at `nlsr.conf
-<https://github.com/named-data/NLSR/blob/master/nlsr.conf>`_ for a sample
-configuration. For details on configuring a router, please refer to
-:doc:`ROUTER-CONFIG`. For details on security configuration, please refer to
-:doc:`SECURITY-CONFIG`.
+NLSR. Please take a look at :doc:`manpages/nlsr.conf` for a sample configuration. For
+details on configuring a router, please refer to :doc:`ROUTER-CONFIG`. For details on
+security configuration, please refer to :doc:`SECURITY-CONFIG`.
Running
-------
@@ -33,17 +31,15 @@
nlsr
-NLSR will look for the default configuration file, nlsr.conf, in the
-current directory.
+NLSR will look for the default configuration file, ``nlsr.conf``, in the current directory.
-You can also run ``nlsr -f`` with the absolute path of
-the configuration file:
+You can also run ``nlsr -f`` with the absolute path of the configuration file:
::
- nlsr -f /nlsr/nlsr.conf
+ nlsr -f /usr/local/etc/ndn/nlsr.conf
-To run NLSR as daemon, use the -d flag:
+To run NLSR as daemon, use the ``-d`` flag:
::
diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst
index d1e89f1..900e839 100644
--- a/docs/INSTALL.rst
+++ b/docs/INSTALL.rst
@@ -7,19 +7,20 @@
Prerequisites
-------------
-- `NFD`_ and its requirements:
+- `NFD <http://named-data.net/doc/NFD/current/>`_ and its requirements:
-Refer to `Getting started with NFD`_ for detailed installation and running instruction.
+Refer to `Getting started with NFD <http://named-data.net/doc/NFD/current/INSTALL.html>`_
+for detailed installation and running instruction.
- log4cxx library
- On Linux:
+ On Ubuntu Linux:
::
sudo apt-get install liblog4cxx10-dev
- On Mac OSx:
+ On OS X with MacPorts:
::
@@ -27,13 +28,13 @@
- protobuf
- On Linux:
+ On Ubuntu Linux:
::
sudo apt-get install libprotobuf-dev protobuf-compiler
- On Mac OSx:
+ On OS X with MacPorts:
::
@@ -42,7 +43,7 @@
Build
-----
-The following commands should be used to build NLSR:
+Execute the following commands to build NLSR:
::
@@ -50,17 +51,14 @@
./waf
sudo ./waf install
-Refer to ./waf –help for more options that can be used during the configure
-stage and how to properly configure NLSR.
+Refer to ``./waf –help`` for more options that can be used during the configure stage and
+how to properly configure NLSR.
-If your pkgconfig path is not set properly you can do following before
-running ``./waf configure``
+If your pkgconfig path is not set properly you can do following before running ``./waf
+configure``
::
export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig/
or
export PKG_CONFIG_PATH=/path/to/pkgconfig/in/your/machine
-
-.. _NFD: http://named-data.net/doc/NFD/current/
-.. _Getting started with NFD: http://named-data.net/doc/NFD/current/INSTALL.html
diff --git a/docs/RELEASE-NOTES.rst b/docs/RELEASE-NOTES.rst
index 9fdc841..9ecf411 100644
--- a/docs/RELEASE-NOTES.rst
+++ b/docs/RELEASE-NOTES.rst
@@ -1,44 +1,42 @@
Release Notes
-==============
+=============
-.. toctree::
-..
+NLSR version 0.1.0 (initial release)
+++++++++++++++++++++++++++++++++++++
-Version 0.1.0 is the initial release of NLSR, a routing protocol for NDN.
+Release date: August 25, 2014
-The main design goal of NLSR is to provide a routing protocol to
-populate `NFD`_’s FIB. NLSR calculates the routing table using link-state
-or hyperbolic routing and produces multiple faces for each reachable
-name prefix in a single authoritative domain.
+The main design goal of NLSR is to provide a routing protocol to populate `NFD's
+<http://named-data.net/doc/NFD/current/>`_ RIB. NLSR calculates the routing table using
+link-state or hyperbolic routing and produces multiple faces for each reachable name
+prefix in a single authoritative domain.
-The current features include:
+**Included features**:
-- **Produce a list of ranked forwarding options for each name prefix to facilitate NDN’s adaptive forwarding strategies**
+- Produce a list of ranked forwarding options for each name prefix to facilitate NDN's adaptive forwarding strategies
-- **Name Prefix advertisement**
+- Name Prefix advertisement
- + Advertise availability of data through the configured router
+ + Advertise availability of content through the configured router
-- **Use ChronoSync to synchronize routers' LSA sequence numbers and Interest/Data to retrieve LSAs**
+- Use `ChronoSync <https://github.com/named-data/ChronoSync>`_ to synchronize routers' LSA sequence numbers and Interest/Data to retrieve LSAs
-- **Limit faces per prefix**
+- Limit faces per prefix
- + Configure maximum number of faces per prefix in NFD's FIB
+ + Configure maximum number of faces per prefix in NFD's RIB
-- **Automatic NFD tunnel configuration and maintainance to neighbors**
+- Automatic NFD tunnel configuration and maintenance to neighbors
-- **Routing protocol**
+- Routing protocol
+ Link State routing
- + **Hyperbolic routing**
+ + Hyperbolic routing
+ Calculates route cost based on a node's polar coordinates
-- **Use a hierarchical trust model for routing within a single administrative domain**
+- Use a hierarchical trust model for routing within a single administrative domain
-- **NFD Forwarding Information Base (FIB) consistency**
+- NFD Routing Information Base (RIB) consistency
+ Provides shortest path next hops for efficient forwarding
- + Keeps NFD's FIB updated on node failure and recovery
-
-.. _NFD: http://named-data.net/doc/NFD/current/
\ No newline at end of file
+ + Keeps NFD's RIB updated on node failure and recovery
diff --git a/docs/ROUTER-CONFIG.rst b/docs/ROUTER-CONFIG.rst
index ab700cf..f8dbf15 100644
--- a/docs/ROUTER-CONFIG.rst
+++ b/docs/ROUTER-CONFIG.rst
@@ -35,7 +35,7 @@
We will walk through setting up the faces and creating the configuration file for
``/ndn/edu/memphis/%C1.Router/router1``.
-Step 1. Ensure nfd is running
+Step 1. Ensuring nfd is running
-------------------------------
Type the following in the terminal:
@@ -52,9 +52,9 @@
---------------------------
Assume that ``/ndn/edu/arizona/%C1.Router/router3`` has hostname ``router3.arizona.edu``,
-``/ndn/edu/colostate/%C1.Router/router2`` has ip address ``79.123.10.145``, and that all
+``/ndn/edu/colostate/%C1.Router/router2`` has IP address ``79.123.10.145``, and that all
routers in the network have agreed to sync data with name prefix ``/ndn/nlsr/sync``.
-``/ndn/edu/memphis/%C1.Router/router1`` will consider face uri
+``/ndn/edu/memphis/%C1.Router/router1`` will consider FaceUri
``udp4://router3.arizona.edu`` for router ``/ndn/edu/arizona/%C1.Router/router3`` and face
uri ``udp4://79.123.10.145`` for router ``/ndn/edu/colostate/%C1.Router/router2``.
@@ -63,7 +63,7 @@
Now, assume that ``/ndn/memphis.edu/router1`` wants to advertise three name prefixes
(``/ndn/memphis/sports/basketball/grizzlies``, ``/ndn/memphis/entertainment/blues``,
-``/ndn/news/memphis/politics/lutherking``). The configuration file with minimum
+``/ndn/news/memphis/politics/lutherking``). The configuration file with the necessary
configuration commands follows:
::
@@ -74,17 +74,17 @@
general
{
; mandatory configuration command section network, site and router
-
network /ndn/ ; name of the network the router belongs to in ndn URI format
site /edu/memphis/ ; name of the site the router belongs to in ndn URI format
router /%C1.Router/router1 ; name of the network the router belongs to in ndn URI format
; lsa-refresh-time is the time in seconds, after which router will refresh its LSAs
-
lsa-refresh-time 1800 ; default value 1800. Valid values 240-7200
- ; log-level is to set the levels of log for NLSR
+ ; InterestLifetime (in seconds) for LSA fetching
+ lsa-interest-lifetime 4 ; default value 4. Valid values 1-60
+ ; log-level is to set the levels of log for NLSR
log-level INFO ; default value INFO, valid value DEBUG, INFO
log-dir /var/log/nlsr/
seq-dir /var/lib/nlsr/
@@ -196,19 +196,19 @@
Expected Output
----------------
-Assuming that all three routers are configured correctly and have converged, ``nfd-status`` in
+Assuming that all three routers are configured correctly and routing has converged, ``nfd-status`` in
``/ndn/edu/colostate/%C1.Router/router2`` will have the following entries for the name
advertised by ``/ndn/edu/memphis/%C1.Router/router1``:
-FIB:
+RIB:
::
- /ndn/memphis/sports/basketball/grizzlies nexthops={faceid=17 (cost=25), faceid=7 (cost=58)}
- /ndn/memphis/entertainment/blues nexthops={faceid=17 (cost=25), faceid=7 (cost=58)}
- /ndn/news/memphis/politics/lutherking nexthops={faceid=17 (cost=25), faceid=7 (cost=58)}
+ /ndn/memphis/entertainment/blues route={faceid=17 (origin=128 cost=25 ChildInherit), faceid=7 (origin=128 cost=58 ChildInherit)}
+ /ndn/memphis/sports/basketball/grizzlies route={faceid=17 (origin=128 cost=25 ChildInherit), faceid=7 (origin=128 cost=58 ChildInherit)}
+ /ndn/news/memphis/politics/lutherking route={faceid=17 (origin=128 cost=25 ChildInherit, faceid=7 (origin=128 cost=58 ChildInherit)}
-This output can be seen by typing ``nfd-status -b`` in the terminal. Please refer to the
+This output can be seen by typing ``nfd-status -r`` in the terminal. Please refer to the
network figure for face IDs.
.. _hyperbolic routing table calculation: http://arxiv.org/abs/0805.1266
diff --git a/docs/SECURITY-CONFIG.rst b/docs/SECURITY-CONFIG.rst
index a010113..7ee9d81 100644
--- a/docs/SECURITY-CONFIG.rst
+++ b/docs/SECURITY-CONFIG.rst
@@ -22,7 +22,7 @@
+ + + + + + +
NLSR NSLR NSLR NSLR NSLR NSLR NSLR
-Each entity’s name and corresponding certificate name follow the
+Each entity's name and corresponding certificate name follow the
convention below:
======== ===================================================== ================================= ===============================================
diff --git a/docs/conf.py b/docs/conf.py
index 247653a..83e251b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -32,6 +32,19 @@
'sphinx.ext.todo',
]
+def addExtensionIfExists(extension):
+ try:
+ __import__(extension)
+ extensions.append(extension)
+ except ImportError:
+ 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('.', '-'))
+
+if os.getenv('GOOGLE_ANALYTICS', None):
+ addExtensionIfExists('sphinxcontrib.googleanalytics')
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -224,9 +237,14 @@
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- # ('manpages/nlsr', 'nlsr', u'Named Data Link State Routing Protocol Daemon', None, 1),
+ ('manpages/nlsr', 'nlsr', u'Named Data Link State Routing Protocol Daemon', None, 1),
+ ('manpages/nlsr.conf', 'nlsr.conf', u'Named Data Link State Routing Protocol Daemon config file', None, 5),
]
# If true, show URL addresses after external links.
#man_show_urls = False
+
+if os.getenv('GOOGLE_ANALYTICS', None):
+ googleanalytics_id = os.environ['GOOGLE_ANALYTICS']
+ googleanalytics_enabled = True
diff --git a/docs/doxygen.conf.in b/docs/doxygen.conf.in
index 544e885..c8ecebb 100644
--- a/docs/doxygen.conf.in
+++ b/docs/doxygen.conf.in
@@ -801,7 +801,7 @@
# that contain example code fragments that are included (see the \include
# command).
-EXAMPLE_PATH = examples/
+EXAMPLE_PATH =
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
diff --git a/docs/index.rst b/docs/index.rst
index b990ea6..77d189f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,23 +1,26 @@
NLSR - Named Data Link State Routing Protocol
=============================================
-NLSR is a routing protocol in NDN that populates NDN’s Forwarding Information Base. NLSR
-will continue to evolve alongside the Named Data Networking `protocol`_.
+NLSR is a routing protocol in NDN that populates NDN's Routing Information Base. NLSR will
+continue to evolve alongside the Named Data Networking `protocol
+<http://named-data.net/doc/ndn-tlv/>`_.
NLSR is an open and free software package licensed under the GPL 3.0 license and free to
all Internet users and developers. For more information about the licensing details and
-limitations, refer to `COPYING.md`_.
+limitations, refer to `COPYING.md
+<https://github.com/named-data/NLSR/blob/master/COPYING.md>`_.
-NLSR is developed by the members of the `NSF-sponsored NDN project team`_. For more
-details, please refer to `AUTHORS.md`_. Bug reports and feedback are highly appreciated
-and can be made through the `Redmine site`_.
+NLSR is developed by the members of the `NSF-sponsored NDN project team
+<http://named-data.net/project/participants/>`_. For more details, please refer to
+`AUTHORS.md <https://github.com/named-data/NLSR/blob/master/AUTHORS.md>`_. Bug reports and
+feedback are highly appreciated and can be made through the `NLSR Wiki`_.
-The main design goal of NLSR is to provide a routing protocol to populate NDN’s FIB. NLSR
+The main design goal of NLSR is to provide a routing protocol to populate NDN's FIB. NLSR
calculates the routing table using link-state or hyperbolic routing and produces multiple
faces for each reachable name prefix in a single authoritative domain. NLSR will continue
to evolve over time to include neighbor discovery and to become a full fledged
-inter-domain routing protocol for NDN. The project design is presented in full detail
-in the `NLSR Paper`_.
+inter-domain routing protocol for NDN. The project design is presented in full detail in
+the `NLSR Paper`_.
NLSR Documentation
-------------------
@@ -31,32 +34,28 @@
GETTING-STARTED
ROUTER-CONFIG
SECURITY-CONFIG
+ manpages
- :doc:`INSTALL`
- :doc:`GETTING-STARTED`
- :doc:`ROUTER-CONFIG`
- :doc:`SECURITY-CONFIG`
- :doc:`RELEASE-NOTES`
+- :doc:`manpages`
Downloading
----------------
+-----------
-- `Github NLSR repository`_
+- `GitHub NLSR repository <https://github.com/named-data/NLSR>`_
Additional information
----------------------
- `NLSR Wiki`_
-.. _protocol: http://named-data.net/doc/ndn-tlv/
+- `NLSR Paper`_
+ Detailed explanation of the NLSR design
-.. _Github NLSR repository: https://github.com/named-data/NLSR
-.. _NLSR Wiki: http://redmine.named-data.net/projects/nlsr/wiki/
-
-.. _COPYING.md: https://github.com/named-data/NLSR/blob/master/COPYING.md
-.. _NSF-sponsored NDN project team: http://named-data.net/project/participants/
-.. _AUTHORS.md: https://github.com/named-data/NLSR/blob/master/AUTHORS.md
-.. _Redmine site: http://redmine.named-data.net/projects/nlsr
-
+.. _NLSR Wiki: http://redmine.named-data.net/projects/nlsr
.. _NLSR Paper: http://conferences.sigcomm.org/sigcomm/2013/papers/icn/p15.pdf
diff --git a/docs/manpages.rst b/docs/manpages.rst
new file mode 100644
index 0000000..40bd0de
--- /dev/null
+++ b/docs/manpages.rst
@@ -0,0 +1,9 @@
+.. _Manpages:
+
+Manpages
+========
+
+.. toctree::
+ manpages/nlsr
+ manpages/nlsr.conf
+ :maxdepth: 1
diff --git a/docs/manpages/nlsr.conf.rst b/docs/manpages/nlsr.conf.rst
new file mode 100644
index 0000000..9ab5860
--- /dev/null
+++ b/docs/manpages/nlsr.conf.rst
@@ -0,0 +1,13 @@
+nlsr.conf
+=========
+
+Description
+-----------
+
+NLSR config file
+
+Example
+-------
+
+.. literalinclude:: ../../nlsr.conf
+ :linenos:
diff --git a/docs/manpages/nlsr.rst b/docs/manpages/nlsr.rst
new file mode 100644
index 0000000..3dd0927
--- /dev/null
+++ b/docs/manpages/nlsr.rst
@@ -0,0 +1,47 @@
+nlsr
+====
+
+Usage
+-----
+
+::
+
+ nlsr [options]
+
+
+Description
+-----------
+
+``nlsr`` is a daemon that implements routing protocol in NDN to populates NDN's Routing
+Information Base.
+
+Options:
+--------
+
+
+``-d``
+ Run in daemon mode
+
+``-f <FILE>``
+ Specify configuration file name (default: ``./nlsr.conf``)
+
+``-V``
+ Display version information
+
+``-h``
+ Display this help message
+
+Examples
+--------
+
+To run NLSR daemon and use a configuration file from the ``/path/to`` directory.
+
+::
+
+ nlsr -f /path/to/nlsr.conf
+
+To run NLSR as daemon, use the ``-d`` flag:
+
+::
+
+ nlsr -d
diff --git a/docs/named_data_theme/named_data_footer.html b/docs/named_data_theme/named_data_footer.html
index 77fc327..86c022b 100644
--- a/docs/named_data_theme/named_data_footer.html
+++ b/docs/named_data_theme/named_data_footer.html
@@ -18,7 +18,5 @@
</small></address>
<!--END !GENERATE_TREEVIEW-->
-<script type="text/javascript">
-</script>
</body>
</html>