docs: various fixes and cleanups
Change-Id: Ib20f89395bf7864e04080c0e69aec93ab8099a47
diff --git a/docs/RELEASE-NOTES.rst b/docs/RELEASE-NOTES.rst
index 43c2a86..04e2f84 100644
--- a/docs/RELEASE-NOTES.rst
+++ b/docs/RELEASE-NOTES.rst
@@ -1,4 +1,4 @@
-PSync Release Notes
-===================
+Release Notes
+=============
-.. include:: release-notes-latest.rst
\ No newline at end of file
+.. include:: release-notes-latest.rst
diff --git a/docs/conf.py b/docs/conf.py
index 2ec076b..495d441 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,10 +1,8 @@
-# -*- coding: utf-8 -*-
-#
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Path setup --------------------------------------------------------------
@@ -20,13 +18,13 @@
# -- Project information -----------------------------------------------------
project = u'PSync: Full/Partial Synchronization Protocol for NDN'
-copyright = u'Copyright © 2018-2020 Named Data Networking Project.'
+copyright = u'Copyright © 2018-2021 Named Data Networking Project.'
author = u'Named Data Networking Project'
-# The short X.Y version
+# The short X.Y version.
#version = ''
-# The full version, including alpha/beta/rc tags
+# The full version, including alpha/beta/rc tags.
#release = ''
# There are two options for replacing |today|: either, you set today to some
@@ -40,7 +38,7 @@
# If your documentation needs a minimal Sphinx version, state it here.
#
-needs_sphinx = '1.1'
+needs_sphinx = '1.3'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -87,6 +85,12 @@
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
+html_copy_source = False
+html_show_sourcelink = False
+
+# Disable syntax highlighting of code blocks by default.
+highlight_language = 'none'
+
# -- Options for LaTeX output ------------------------------------------------
diff --git a/docs/doxygen.conf.in b/docs/doxygen.conf.in
index 14dce64..16fe960 100644
--- a/docs/doxygen.conf.in
+++ b/docs/doxygen.conf.in
@@ -1739,16 +1739,6 @@
LATEX_HIDE_INDICES = NO
-# If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source
-# code with syntax highlighting in the LaTeX output.
-#
-# Note that which sources are shown also depends on other settings such as
-# SOURCE_BROWSER.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_LATEX is set to YES.
-
-LATEX_SOURCE_CODE = NO
-
# The LATEX_BIB_STYLE tag can be used to specify the style to use for the
# bibliography, e.g. plainnat, or ieeetr. See
# http://en.wikipedia.org/wiki/BibTeX and \cite for more info.
@@ -1821,16 +1811,6 @@
RTF_EXTENSIONS_FILE =
-# If the RTF_SOURCE_CODE tag is set to YES then doxygen will include source code
-# with syntax highlighting in the RTF output.
-#
-# Note that which sources are shown also depends on other settings such as
-# SOURCE_BROWSER.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_RTF is set to YES.
-
-RTF_SOURCE_CODE = NO
-
#---------------------------------------------------------------------------
# Configuration options related to the man page output
#---------------------------------------------------------------------------
@@ -1920,15 +1900,6 @@
DOCBOOK_OUTPUT = docbook
-# If the DOCBOOK_PROGRAMLISTING tag is set to YES, doxygen will include the
-# program listings (including syntax highlighting and cross-referencing
-# information) to the DOCBOOK output. Note that enabling this will significantly
-# increase the size of the DOCBOOK output.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_DOCBOOK is set to YES.
-
-DOCBOOK_PROGRAMLISTING = NO
-
#---------------------------------------------------------------------------
# Configuration options for the AutoGen Definitions output
#---------------------------------------------------------------------------
diff --git a/docs/examples.rst b/docs/examples.rst
index 9427dfa..bb66270 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -1,5 +1,5 @@
-PSync examples
-==============
+Examples
+========
By default, examples in ``examples/`` folder are not built. To enable them, use
``--with-examples`` configure option. For example:
@@ -9,12 +9,10 @@
./waf configure --with-examples
./waf
+Example binary can be found under ``build/examples``:
-Example binary can be found under ``build/examples``\ :
-
-
-* Full sync : ``psync-full-sync``
-* Partial sync : ``psync-producer`` and ``psync-consumer``
+* 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.
@@ -44,7 +42,7 @@
* Sample output:
-.. code-block:: bash
+::
1546280442.096296 INFO: [examples.PartialSyncProducerApp] Publish: /a-1/1
1546280456.053138 INFO: [examples.PartialSyncProducerApp] Publish: /a-6/1
@@ -77,7 +75,7 @@
* 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
@@ -124,7 +122,7 @@
* 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
@@ -139,10 +137,9 @@
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
diff --git a/docs/index.rst b/docs/index.rst
index 226ca26..8dda472 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,29 +1,34 @@
PSYNC - Partial/Full Sync Library based on BF and IBF
=====================================================
-PSync is an ndn-cxx based C++ library for name synchronization that uses
+PSync is a C++ library for name synchronization that 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 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 uses the `ndn-cxx <https://github.com/named-data/ndn-cxx>`__ 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.
+Contributing
+------------
-Please submit any bugs or issues to the `PSync issue tracker
-<https://redmine.named-data.net/projects/PSync/issues>`__.
+We greatly appreciate contributions to the PSync code base, provided that they are
+licensed under the LGPL 3.0+ or a compatible license (see `COPYING.md
+<https://github.com/named-data/PSync/blob/master/COPYING.md>`__ for more information).
+If you are new to the NDN software community, please read the `Contributor's Guide
+<https://github.com/named-data/.github/blob/master/CONTRIBUTING.md>`__ to get started.
+
+Please submit any bug reports or feature requests to the `PSync issue tracker
+<https://redmine.named-data.net/projects/psync/issues>`__.
PSync Documentation
-------------------
.. toctree::
:hidden:
- :maxdepth: 3
+ :maxdepth: 2
install
examples
@@ -33,4 +38,4 @@
- :doc:`install`
- :doc:`examples`
- :doc:`RELEASE-NOTES`
-- :doc:`releases`
\ No newline at end of file
+- :doc:`releases`
diff --git a/docs/install.rst b/docs/install.rst
index 64a96f6..6704d23 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -1,8 +1,5 @@
-PSync Installation Instructions
-===============================
-
-.. toctree::
-..
+Installation Instructions
+=========================
Prerequisites
-------------
@@ -12,10 +9,10 @@
Build
-----
-Execute the following commands to build PSync:
+Run the following commands to build PSync:
-::
+.. code-block:: sh
./waf configure
./waf
- sudo ./waf install
\ No newline at end of file
+ sudo ./waf install
diff --git a/docs/release-notes/release-notes-0.1.0.rst b/docs/release-notes/release-notes-0.1.0.rst
index 528f04e..1a137a4 100644
--- a/docs/release-notes/release-notes-0.1.0.rst
+++ b/docs/release-notes/release-notes-0.1.0.rst
@@ -1,14 +1,15 @@
PSync version 0.1.0
-------------------
-Release date: January 25, 2019
+*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.
+Version 0.1.0 is the initial release of PSync. The 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
+PSync uses the `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.
diff --git a/docs/release-notes/release-notes-0.2.0.rst b/docs/release-notes/release-notes-0.2.0.rst
index c3e69da..0eaa225 100644
--- a/docs/release-notes/release-notes-0.2.0.rst
+++ b/docs/release-notes/release-notes-0.2.0.rst
@@ -1,13 +1,17 @@
PSync version 0.2.0
-------------------
-**New features**:
+*Release date: February 2, 2020*
+
+New features
+^^^^^^^^^^^^
- **breaking change** Compress Sync Data in Full Sync by default (:issue:`5061`, :issue:`4917`)
- Support various compression schemes for compressing IBF and Sync Data (:issue:`5061`)
-**Changes**
+Changes
+^^^^^^^
- Use constant interest timeout for (discovery) sync Interest in Segment Fetcher (:issue:`4945`)
- Make default jitter shorter, react to NACK after jitter
-- Use boost::bimap instead of two std::map variables to store hash to prefix matching
+- Use ``boost::bimap`` instead of two ``std::map`` variables to store hash to prefix matching
diff --git a/docs/release-notes/release-notes-0.3.0.rst b/docs/release-notes/release-notes-0.3.0.rst
index f5d2e10..20c9360 100644
--- a/docs/release-notes/release-notes-0.3.0.rst
+++ b/docs/release-notes/release-notes-0.3.0.rst
@@ -1,6 +1,8 @@
PSync version 0.3.0
-------------------
+*Release date: January 3, 2021*
+
The build requirements have been increased to require Clang >= 4.0, Xcode >= 9.0, and Python >= 3.6.
Meanwhile, it is *recommended* to use GCC >= 7.4.0 and Boost >= 1.65.1.
This effectively drops official support for Ubuntu 16.04 when using distribution-provided Boost
@@ -12,7 +14,6 @@
^^^^^^^^^^^^
- **breaking** Consumer: change hello data callback to include sequence number (:issue:`5122`)
-- Support various compression schemes for compressing IBF and Sync Data (:issue:`5061`)
Improvements and bug fixes
^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -22,4 +23,3 @@
- Consumer reacts faster on sync Interest timeout (:issue:`5124`)
- Move private classes and functions to ``psync::detail`` namespace
- Improved unit tests
-
diff --git a/docs/releases.rst b/docs/releases.rst
index d66aaf2..148f90c 100644
--- a/docs/releases.rst
+++ b/docs/releases.rst
@@ -1,10 +1,9 @@
PSync Versions
-++++++++++++++
+==============
.. toctree::
- :hidden:
+ :glob:
:maxdepth: 1
+ :reversed:
- release-notes/release-notes-0.3.0
- release-notes/release-notes-0.2.0
- release-notes/release-notes-0.1.0
+ release-notes/*