docs: improve formatting and document structure
Change-Id: I4b0b4cc3eae000aa1c988c5d308c3f78052ad96d
diff --git a/.jenkins.d/00-deps.sh b/.jenkins.d/00-deps.sh
index 9b1e073..c114f8d 100755
--- a/.jenkins.d/00-deps.sh
+++ b/.jenkins.d/00-deps.sh
@@ -21,7 +21,7 @@
if [[ $ID == macos ]]; then
if [[ -n $GITHUB_ACTIONS ]]; then
- export HOMEBREW_NO_INSTALL_UPGRADE=1
+ export HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK=1
fi
brew update
brew install --formula "${FORMULAE[@]}"
diff --git a/COPYING.md b/COPYING.md
index c2796db..0ee9e35 100644
--- a/COPYING.md
+++ b/COPYING.md
@@ -18,9 +18,8 @@
- The waf build system is licensed under the terms of the
[BSD license](https://github.com/named-data/PSync/blob/master/waf)
-
The LGPL and GPL licenses are provided below in this file. For more information
-about these licenses, see https://www.gnu.org/licenses/
+about these licenses, see <https://www.gnu.org/licenses/>
--------------------------------------------------------------------------------
diff --git a/README.md b/README.md
index 8d03a64..45e1500 100644
--- a/README.md
+++ b/README.md
@@ -43,12 +43,11 @@
## Contributing
We greatly appreciate contributions to the PSync code base, provided that they are
-licensed under the LGPL 3.0+ or a compatible license (see below).
-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.
+licensed under the GNU LGPL version 3 or a compatible license.
+If you are new to the NDN software community, please read our [Contributor's Guide](
+https://github.com/named-data/.github/blob/master/CONTRIBUTING.md) to get started.
## License
-PSync is an open source project licensed under the LGPL version 3.
-See [`COPYING.md`](COPYING.md) for more information.
+PSync is free software distributed under the GNU Lesser General Public License version 3.
+See [`COPYING.md`](COPYING.md) for details.
diff --git a/docs/conf.py b/docs/conf.py
index 8b9cea6..d4bf63c 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -10,7 +10,7 @@
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = 'PSync: Partial/Full Synchronization Protocol for NDN'
-copyright = 'Copyright © 2018-2022 Named Data Networking Project.'
+copyright = 'Copyright © 2018-2023 Named Data Networking Project.'
author = 'Named Data Networking Project'
# The short X.Y version.
diff --git a/docs/examples.rst b/docs/examples.rst
index bb66270..bcd0517 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -1,155 +1,141 @@
Examples
========
-By default, examples in ``examples/`` folder are not built. To enable them, use
-``--with-examples`` configure option. For example:
+The example programs in the ``examples/`` subdirectory are not built by default.
+To enable them, use the ``--with-examples`` configure option:
.. code-block:: bash
./waf configure --with-examples
./waf
-Example binary can be found under ``build/examples``:
+Once built, the example binaries 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.
+If the library is installed to the system using ``./waf install``, then the examples
+will also be 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:
+The 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:
+* Enable logging for the producer.
-.. code-block:: bash
+ .. code-block:: bash
- export NDN_LOG=examples.PartialSyncProducerApp=INFO
+ export NDN_LOG="examples.PartialSyncProducerApp=INFO"
+* Start the producer that will listen on ``/sync`` and publish one update for each
+ of ``/a-0`` ... ``/a-9``.
-* Start the producer that will listen on /sync and publish 1 update for /a-0 ... /a-9 each.
+ .. code-block:: bash
-.. code-block:: bash
+ psync-producer /sync /a 10 1
- psync-producer /sync /a 10 1
+* Sample output::
-
-* Sample output:
-
-::
-
- 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
+ 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:
+* In a new terminal, enable logging for the consumer.
-.. code-block:: bash
+ .. code-block:: bash
- export NDN_LOG=examples.PartialSyncConsumerApp=INFO
+ export NDN_LOG="examples.PartialSyncConsumerApp=INFO"
+* Run the consumer to subscribe to 5 random prefixes from the publisher on ``/sync``.
-* Run the consumer to subscribe to 5 random prefixes from the publisher on /sync
+ .. code-block:: bash
-.. code-block:: bash
-
- psync-consumer /sync 5
-
+ psync-consumer /sync 5
* Sample output from the consumer shows that it received updates only
- for the subscribed prefixes:
+ for the subscribed prefixes::
-::
-
- 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
+ 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:
+To demonstrate the full sync mode of PSync, ``psync-full-sync`` can be run on a
+machine after starting NFD.
+* Enable logging for the full sync demo app.
-* Enable the logs for full sync:
+ .. code-block:: bash
-.. code-block:: bash
+ export NDN_LOG="examples.FullSyncApp=INFO"
- 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
-* 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.
+ psync-full-sync /sync /a 2 3
-.. code-block:: bash
+* Repeat for another user prefix, to simulate node *b*.
- psync-full-sync /sync /a 2 3
+ .. code-block:: bash
+ psync-full-sync /sync /b 2 3
-* Repeat for another user prefix, to simulate node b:
+ We should see that node *a* and node *b* have received each other's updates.
-.. code-block:: bash
+* Sample output from node *a* shows that it received all updates from node *b*
+ successfully::
- psync-full-sync /sync /b 2 3
+ 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
-We should see that node a and node b have received each other's updates.
+* Sample output from node *b*::
-
-* Sample output from node a shows that it received all updates
- from node b successfully:
-
-::
-
- 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:
-
-::
-
- 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
+ 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 ea4ae0a..b7aa61f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,5 +1,14 @@
-PSync - Partial/Full Sync Library based on BF and IBF
-=====================================================
+PSync: Partial/Full Sync Library based on BF and IBF
+====================================================
+
+.. toctree::
+ :hidden:
+ :maxdepth: 2
+
+ install
+ examples
+ release-notes
+ releases
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>`__.
@@ -11,31 +20,22 @@
PSync uses the `ndn-cxx <https://github.com/named-data/ndn-cxx>`__ library.
+Documentation
+-------------
+
+- :doc:`install`
+- :doc:`examples`
+- :doc:`release-notes`
+- :doc:`releases`
+
Contributing
------------
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
+licensed under the GNU LGPL version 3 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
+If you are new to the NDN software community, please read our `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: 2
-
- install
- examples
- release-notes
- releases
-
-- :doc:`install`
-- :doc:`examples`
-- :doc:`release-notes`
-- :doc:`releases`
diff --git a/docs/release-notes/release-notes-0.1.0.rst b/docs/release-notes/release-notes-0.1.0.rst
index 1a137a4..5b1ad72 100644
--- a/docs/release-notes/release-notes-0.1.0.rst
+++ b/docs/release-notes/release-notes-0.1.0.rst
@@ -4,12 +4,12 @@
*Release date: January 25, 2019*
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>`_.
+<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 the `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.
@@ -30,6 +30,6 @@
- **Miscellaneous**
- + Uses ndn-cxx **SegmentFetcher** to segment hello and sync data.
+ + 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.
+ + Examples are provided in ``examples`` folder to show how to use the library.
diff --git a/docs/release-notes/release-notes-0.2.0.rst b/docs/release-notes/release-notes-0.2.0.rst
index 0eaa225..4e0d1a0 100644
--- a/docs/release-notes/release-notes-0.2.0.rst
+++ b/docs/release-notes/release-notes-0.2.0.rst
@@ -6,12 +6,12 @@
New features
^^^^^^^^^^^^
-- **breaking change** Compress Sync Data in Full Sync by default (:issue:`5061`, :issue:`4917`)
+- *(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
-^^^^^^^
+Improvements and bug fixes
+^^^^^^^^^^^^^^^^^^^^^^^^^^
-- Use constant interest timeout for (discovery) sync Interest in Segment Fetcher (:issue:`4945`)
+- Use constant interest timeout for (discovery) Sync Interest in ``SegmentFetcher`` (: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
diff --git a/docs/release-notes/release-notes-0.3.0.rst b/docs/release-notes/release-notes-0.3.0.rst
index 20c9360..ea9a61d 100644
--- a/docs/release-notes/release-notes-0.3.0.rst
+++ b/docs/release-notes/release-notes-0.3.0.rst
@@ -8,18 +8,22 @@
This effectively drops official support for Ubuntu 16.04 when using distribution-provided Boost
packages -- PSync may still work on this platform, but we provide no official support for it.
-We have taken some steps to be endian safe but PSync is not completely endian safe yet (:issue:`4818`)
-
New features
^^^^^^^^^^^^
-- **breaking** Consumer: change hello data callback to include sequence number (:issue:`5122`)
+- *(breaking change)* Consumer: change hello data callback to include sequence number (:issue:`5122`)
Improvements and bug fixes
^^^^^^^^^^^^^^^^^^^^^^^^^^
-- **breaking** IBLT: make encoding endian safe (:issue:`5076`)
+- *(breaking change)* IBLT: make encoding endian safe (:issue:`5076`)
- Reset cached wire encoding after adding names (:issue:`5083`)
-- Consumer reacts faster on sync Interest timeout (:issue:`5124`)
+- Consumer reacts faster on Sync Interest timeout (:issue:`5124`)
- Move private classes and functions to ``psync::detail`` namespace
- Improved unit tests
+
+Known issues
+^^^^^^^^^^^^
+
+- We have taken some steps to be endian safe but PSync is not completely endian safe yet
+ (:issue:`4818`)