docs: prepare version 0.1.0 release notes
Change-Id: I588e97d4dec76cd6f4ffbda487de5b7cbe412219
diff --git a/AUTHORS.md b/AUTHORS.md
index 63d1877..5800355 100644
--- a/AUTHORS.md
+++ b/AUTHORS.md
@@ -1,10 +1,17 @@
PSync authors
=============
-## Author(s):
+## Main Project Author(s):
+
+The University of Memphis:
* Ashlesh Gawande <https://www.linkedin.com/in/agawande>
* Minsheng Zhang <https://www.linkedin.com/in/minsheng-zhang-032023a1>
+* Lan Wang <http://www.cs.memphis.edu/~lanwang/>
+
+## Contributer(s):
+
+* Junxiao Shi <https://www.linkedin.com/in/shijunxiao>
## Technical advisor(s):
@@ -12,4 +19,4 @@
## Special thanks to:
-* Davide Pesavento <https://www.linkedin.com/in/davidepesavento>
+* Davide Pesavento <https://www.linkedin.com/in/davidepesavento>
\ No newline at end of file
diff --git a/docs/RELEASE-NOTES.rst b/docs/RELEASE-NOTES.rst
new file mode 100644
index 0000000..43c2a86
--- /dev/null
+++ b/docs/RELEASE-NOTES.rst
@@ -0,0 +1,4 @@
+PSync Release Notes
+===================
+
+.. include:: release-notes-latest.rst
\ No newline at end of file
diff --git a/docs/_static/.gitignore b/docs/_static/.gitignore
new file mode 100644
index 0000000..d6b7ef3
--- /dev/null
+++ b/docs/_static/.gitignore
@@ -0,0 +1,2 @@
+*
+!.gitignore
diff --git a/docs/conf.py b/docs/conf.py
index f27bd34..425f489 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -20,7 +20,7 @@
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
@@ -64,8 +64,8 @@
master_doc = 'index'
# General information about the project.
-project = u'PSync: A Synchronization Protocol in NDN'
-copyright = u'{}, Named Data Networking Project'.format(datetime.date.today().year)
+project = u'PSync: A Synchronization Protocol for NDN'
+copyright = u'2018-{}, Named Data Networking Project'.format(datetime.date.today().year)
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@@ -140,7 +140,7 @@
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
+html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
@@ -256,4 +256,4 @@
googleanalytics_id = os.environ['GOOGLE_ANALYTICS']
googleanalytics_enabled = True
-exclude_patterns = ['RELEASE_NOTES.rst']
+redmine_project_url = "https://redmine.named-data.net/"
diff --git a/docs/doxygen.conf.in b/docs/doxygen.conf.in
index bcde9c6..95b2bbe 100644
--- a/docs/doxygen.conf.in
+++ b/docs/doxygen.conf.in
@@ -140,7 +140,7 @@
# shortest path that makes the file name unique will be used
# The default value is: YES.
-FULL_PATH_NAMES = NO
+FULL_PATH_NAMES = YES
# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path.
# Stripping is only done if one of the specified strings matches the left-hand
@@ -152,7 +152,7 @@
# will be relative from the directory where doxygen is started.
# This tag requires that the tag FULL_PATH_NAMES is set to YES.
-STRIP_FROM_PATH =
+STRIP_FROM_PATH = ..
# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
# path mentioned in the documentation of a class, which tells the reader which
@@ -451,7 +451,7 @@
# for Java sources.
# The default value is: YES.
-EXTRACT_LOCAL_CLASSES = YES
+EXTRACT_LOCAL_CLASSES = NO
# This flag is only useful for Objective-C code. If set to YES, local methods,
# which are defined in the implementation section but not in the interface are
@@ -867,7 +867,7 @@
# irrespective of the value of the RECURSIVE tag.
# The default value is: NO.
-EXAMPLE_RECURSIVE = NO
+EXAMPLE_RECURSIVE = YES
# The IMAGE_PATH tag can be used to specify one or more files or directories
# that contain images that are to be included in the documentation (see the
@@ -2051,7 +2051,11 @@
PREDEFINED = DOXYGEN \
PSYNC_PUBLIC_WITH_TESTS_ELSE_PRIVATE=private \
- NDN_CXX_DECLARE_WIRE_ENCODE_INSTANTIATIONS(x)=
+ NDN_CXX_DECLARE_WIRE_ENCODE_INSTANTIATIONS(x)= \
+ NDN_LOG_INIT(x)= \
+ PUBLIC_WITH_TESTS_ELSE_PROTECTED=protected \
+ PUBLIC_WITH_TESTS_ELSE_PRIVATE=private \
+ PROTECTED_WITH_TESTS_ELSE_PRIVATE=private
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The
diff --git a/docs/examples.rst b/docs/examples.rst
new file mode 100644
index 0000000..9427dfa
--- /dev/null
+++ b/docs/examples.rst
@@ -0,0 +1,158 @@
+PSync examples
+==============
+
+By default, examples in ``examples/`` folder are not built. To enable them, use
+``--with-examples`` configure option. For example:
+
+.. code-block:: bash
+
+ ./waf configure --with-examples
+ ./waf
+
+
+Example binary can be found under ``build/examples``\ :
+
+
+* Full sync : ``psync-full-sync``
+* Partial sync : ``psync-producer`` and ``psync-consumer``
+
+If the library is installed to the system using ``./waf install`` then the examples
+are also installed and can be executed directly.
+
+Partial Sync Example
+--------------------
+
+Partial sync example of PSync has two parts: producer and consumer.
+These can be run on a machine after starting NFD:
+
+Producer
+^^^^^^^^
+
+* Enable the logs for producer:
+
+.. code-block:: bash
+
+ export NDN_LOG=examples.PartialSyncProducerApp=INFO
+
+
+* Start the producer that will listen on /sync and publish 1 update for /a-0 ... /a-9 each.
+
+.. code-block:: bash
+
+ psync-producer /sync /a 10 1
+
+
+* Sample output:
+
+.. code-block:: bash
+
+ 1546280442.096296 INFO: [examples.PartialSyncProducerApp] Publish: /a-1/1
+ 1546280456.053138 INFO: [examples.PartialSyncProducerApp] Publish: /a-6/1
+ 1546280458.210415 INFO: [examples.PartialSyncProducerApp] Publish: /a-8/1
+ 1546280469.954134 INFO: [examples.PartialSyncProducerApp] Publish: /a-5/1
+ 1546280472.487425 INFO: [examples.PartialSyncProducerApp] Publish: /a-2/1
+ 1546280473.466515 INFO: [examples.PartialSyncProducerApp] Publish: /a-7/1
+ 1546280481.882258 INFO: [examples.PartialSyncProducerApp] Publish: /a-0/1
+ 1546280484.201229 INFO: [examples.PartialSyncProducerApp] Publish: /a-4/1
+ 1546280489.348968 INFO: [examples.PartialSyncProducerApp] Publish: /a-9/1
+ 1546280491.420391 INFO: [examples.PartialSyncProducerApp] Publish: /a-3/1
+
+Consumer
+^^^^^^^^
+
+* In a new terminal, enable the logs for consumer:
+
+.. code-block:: bash
+
+ export NDN_LOG=examples.PartialSyncConsumerApp=INFO
+
+
+* Run the consumer to subscribe to 5 random prefixes from the publisher on /sync
+
+.. code-block:: bash
+
+ psync-consumer /sync 5
+
+
+* Sample output from the consumer shows that it received updates only
+ for the subscribed prefixes:
+
+.. code-block:: bash
+
+ 1546280436.502769 INFO: [examples.PartialSyncConsumerApp] Subscribing to: /a-7
+ 1546280436.502888 INFO: [examples.PartialSyncConsumerApp] Subscribing to: /a-9
+ 1546280436.502911 INFO: [examples.PartialSyncConsumerApp] Subscribing to: /a-8
+ 1546280436.502934 INFO: [examples.PartialSyncConsumerApp] Subscribing to: /a-4
+ 1546280436.502956 INFO: [examples.PartialSyncConsumerApp] Subscribing to: /a-5
+ 1546280458.211188 INFO: [examples.PartialSyncConsumerApp] Update: /a-8/1
+ 1546280469.954886 INFO: [examples.PartialSyncConsumerApp] Update: /a-5/1
+ 1546280473.467116 INFO: [examples.PartialSyncConsumerApp] Update: /a-7/1
+ 1546280484.256181 INFO: [examples.PartialSyncConsumerApp] Update: /a-4/1
+ 1546280489.349793 INFO: [examples.PartialSyncConsumerApp] Update: /a-9/1
+
+Full Sync Example
+-----------------
+
+To demonstrate full sync mode of PSync, ``psync-full-sync``
+can be run on a machine after starting NFD:
+
+
+* Enable the logs for full sync:
+
+.. code-block:: bash
+
+ export NDN_LOG=examples.FullSyncApp=INFO
+
+
+* Run the full sync example with sync prefix /sync, user prefix /a,
+ and publish three updates for each user prefix: /a-0 and /a-1. This will simulate node a.
+
+.. code-block:: bash
+
+ psync-full-sync /sync /a 2 3
+
+
+* Repeat for another user prefix, to simulate node b:
+
+.. code-block:: bash
+
+ psync-full-sync /sync /b 2 3
+
+We should see that node a and node b have received each other's updates.
+
+
+* Sample output from node a shows that it received all updates
+ from node b successfully:
+
+.. code-block:: bash
+
+ 1546282730.759387 INFO: [examples.FullSyncApp] Update /b-1/1
+ 1546282741.143225 INFO: [examples.FullSyncApp] Publish: /a-1/1
+ 1546282749.375854 INFO: [examples.FullSyncApp] Publish: /a-0/1
+ 1546282750.263246 INFO: [examples.FullSyncApp] Update /b-0/1
+ 1546282765.875118 INFO: [examples.FullSyncApp] Update /b-1/2
+ 1546282783.777807 INFO: [examples.FullSyncApp] Publish: /a-0/2
+ 1546282794.565507 INFO: [examples.FullSyncApp] Publish: /a-0/3
+ 1546282794.896895 INFO: [examples.FullSyncApp] Publish: /a-1/2
+ 1546282803.839416 INFO: [examples.FullSyncApp] Update /b-0/2
+ 1546282804.785867 INFO: [examples.FullSyncApp] Update /b-1/3
+ 1546282845.273772 INFO: [examples.FullSyncApp] Publish: /a-1/3
+ 1546282855.102790 INFO: [examples.FullSyncApp] Update /b-0/3
+
+
+* Sample output from node b:
+
+.. code-block:: bash
+
+ 1546282730.758296 INFO: [examples.FullSyncApp] Publish: /b-1/1
+ 1546282741.144027 INFO: [examples.FullSyncApp] Update /a-1/1
+ 1546282749.376543 INFO: [examples.FullSyncApp] Update /a-0/1
+ 1546282750.262244 INFO: [examples.FullSyncApp] Publish: /b-0/1
+ 1546282765.296005 INFO: [examples.FullSyncApp] Publish: /b-1/2
+ 1546282783.778769 INFO: [examples.FullSyncApp] Update /a-0/2
+ 1546282794.566485 INFO: [examples.FullSyncApp] Update /a-0/3
+ 1546282795.374339 INFO: [examples.FullSyncApp] Update /a-1/2
+ 1546282803.838394 INFO: [examples.FullSyncApp] Publish: /b-0/2
+ 1546282804.033214 INFO: [examples.FullSyncApp] Publish: /b-1/3
+ 1546282845.274680 INFO: [examples.FullSyncApp] Update /a-1/3
+ 1546282855.101780 INFO: [examples.FullSyncApp] Publish: /b-0/3
diff --git a/docs/index.rst b/docs/index.rst
index d707098..226ca26 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,2 +1,36 @@
PSYNC - Partial/Full Sync Library based on BF and IBF
=====================================================
+
+PSync is an ndn-cxx based C++ library for name synchronization that uses
+
+PSync library implements the `PSync protocol <https://named-data.net/wp-content/uploads/2017/05/scalable_name-based_data_synchronization.pdf>`_. It uses Invertible
+Bloom Lookup Table (IBLT), also known as Invertible Bloom Filter (IBF), to represent the state
+of a producer in partial sync mode and the state of a node in full sync mode. An IBF is a compact data
+structure where difference of two IBFs can be computed efficiently.
+In partial sync, PSync uses a Bloom Filter to represent the subscription of list of the consumer.
+PSync uses `ndn-cxx <https://github.com/named-data/ndn-cxx>`_ library as NDN development
+library.
+
+PSync is an open source project licensed under LGPL 3.0 (see ``COPYING.md`` for more
+detail). We highly welcome all contributions to the PSync code base, provided that
+they can be licensed under LGPL 3.0+ or other compatible license.
+
+Please submit any bugs or issues to the `PSync issue tracker
+<https://redmine.named-data.net/projects/PSync/issues>`__.
+
+PSync Documentation
+-------------------
+
+.. toctree::
+ :hidden:
+ :maxdepth: 3
+
+ install
+ examples
+ RELEASE-NOTES
+ releases
+
+- :doc:`install`
+- :doc:`examples`
+- :doc:`RELEASE-NOTES`
+- :doc:`releases`
\ No newline at end of file
diff --git a/docs/install.rst b/docs/install.rst
new file mode 100644
index 0000000..64a96f6
--- /dev/null
+++ b/docs/install.rst
@@ -0,0 +1,21 @@
+PSync Installation Instructions
+===============================
+
+.. toctree::
+..
+
+Prerequisites
+-------------
+
+- `ndn-cxx <https://named-data.net/doc/ndn-cxx>`_ and its dependencies
+
+Build
+-----
+
+Execute the following commands to build PSync:
+
+::
+
+ ./waf configure
+ ./waf
+ sudo ./waf install
\ No newline at end of file
diff --git a/docs/named_data_theme/layout.html b/docs/named_data_theme/layout.html
index 3d9a27d..aa25686 100644
--- a/docs/named_data_theme/layout.html
+++ b/docs/named_data_theme/layout.html
@@ -40,9 +40,7 @@
<h3>{{ _('Developer documentation') }}</h3>
<ul>
- <li class="toctree-l1"><a class="reference external" href="https://redmine.named-data.net/projects/psync/wiki">PSync Wiki</a></li>
<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>
{%- endblock %}
diff --git a/docs/release-notes-latest.rst b/docs/release-notes-latest.rst
new file mode 120000
index 0000000..9f2f502
--- /dev/null
+++ b/docs/release-notes-latest.rst
@@ -0,0 +1 @@
+release-notes/release-notes-0.1.0.rst
\ No newline at end of file
diff --git a/docs/release-notes/release-notes-0.1.0.rst b/docs/release-notes/release-notes-0.1.0.rst
new file mode 100644
index 0000000..528f04e
--- /dev/null
+++ b/docs/release-notes/release-notes-0.1.0.rst
@@ -0,0 +1,34 @@
+PSync version 0.1.0
+-------------------
+
+Release date: January 25, 2019
+
+Version 0.1.0 is the initial release of PSyncPSync library implements the `PSync protocol <https://named-data.net/wp-content/uploads/2017/05/scalable_name-based_data_synchronization.pdf>`_. It uses Invertible
+Bloom Lookup Table (IBLT), also known as Invertible Bloom Filter (IBF), to represent the state
+of a producer in partial sync mode and the state of a node in full sync mode. An IBF is a compact data
+structure where difference of two IBFs can be computed efficiently.
+In partial sync, PSync uses a Bloom Filter to represent the subscription of list of the consumer.
+PSync uses `ndn-cxx <https://github.com/named-data/ndn-cxx>`_ library as NDN development
+library.
+
+PSync is an open source project licensed under LGPL 3.0. We highly welcome all contributions to the PSync code base, provided that they can be licensed under LGPL 3.0+ or other compatible license.
+
+PSync supports the following features:
+
+- **Partial Synchronization**
+
+ + Allows consumers to subscribe to a subset of a producer's offered prefixes.
+ + Consumer can sync with any replicated producer in the same sync group.
+ + A PartialProducer class to publish prefixes and updates.
+ + A Consumer class to subscribe to the producer (hello) and listen for updates (sync).
+
+- **Full Synchronization**
+
+ + Similar to ChronoSync, allows full synchronization of names amongst all the nodes in the sync group.
+ + FullProducer class can be used start syncing with a sync group.
+
+- **Miscellaneous**
+
+ + Uses ndn-cxx **SegmentFetcher** to segment hello and sync data.
+ + Provide a SegmentPublisher that can be used by other NDN applications.
+ + Examples are provided in `examples` folder to show how to use the library.
diff --git a/docs/releases.rst b/docs/releases.rst
new file mode 100644
index 0000000..6d904e2
--- /dev/null
+++ b/docs/releases.rst
@@ -0,0 +1,8 @@
+PSync Versions
+++++++++++++++
+
+.. toctree::
+ :hidden:
+ :maxdepth: 1
+
+ release-notes/release-notes-0.1.0
\ No newline at end of file