docs: fix/improve the structure of several documents
Change-Id: Ib8acd4bf29baf19b78d25cabc1a873eeeec15da6
diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst
index 82fa64b..755da6f 100644
--- a/docs/INSTALL.rst
+++ b/docs/INSTALL.rst
@@ -41,39 +41,34 @@
To build ndn-cxx from source, one must first install a C++ compiler and all necessary
development tools and libraries:
-- On **Debian** and **Ubuntu**
+- On **Debian** and **Ubuntu**, run in a terminal:
- In a terminal, enter::
+ .. code-block:: shell
- sudo apt install build-essential libboost-all-dev libssl-dev libsqlite3-dev pkgconf python3
+ sudo apt install build-essential libboost-all-dev libssl-dev libsqlite3-dev pkgconf python3
-- On **CentOS** and **Fedora**
+- On **CentOS** and **Fedora**, run in a terminal:
- In a terminal, enter::
+ .. code-block:: shell
- sudo dnf install gcc-c++ boost-devel openssl-devel sqlite-devel pkgconf python3
+ sudo dnf install gcc-c++ boost-devel openssl-devel sqlite-devel pkgconf python3
- On **macOS**
- * Install either Xcode (from the App Store) or the Command Line Tools
- (with ``xcode-select --install``)
+ * Install either Xcode (from the App Store) or the Command Line Tools
+ (with ``xcode-select --install``)
- * If using Homebrew (recommended), enter the following in a terminal:
+ * If using Homebrew (recommended), enter the following in a terminal:
- .. code-block:: sh
+ .. code-block:: shell
- brew install boost openssl pkgconf
+ brew install boost openssl pkgconf
- .. warning::
+- On **FreeBSD**, run in a terminal:
- If a major OS upgrade is performed after installing the dependencies
- with Homebrew, remember to reinstall all packages.
+ .. code-block:: shell
-- On **FreeBSD**
-
- In a terminal, enter::
-
- sudo pkg install boost-libs openssl sqlite3 pkgconf python3
+ sudo pkg install boost-libs openssl sqlite3 pkgconf python3
Optional
~~~~~~~~
@@ -83,56 +78,57 @@
- doxygen
- graphviz
-- sphinx
-- sphinxcontrib-doxylink
+- `sphinx <https://www.sphinx-doc.org/>`__
+- `sphinxcontrib-doxylink <https://github.com/sphinx-contrib/doxylink>`__
+- `furo <https://pradyunsg.me/furo/>`__
The following lists the steps to install these prerequisites on various common platforms.
-.. note::
+.. tip::
On Linux, you may need to add ``$HOME/.local/bin`` to the ``PATH`` environment variable
for your user, for example:
- .. code-block:: sh
+ .. code-block:: shell
- export PATH="${HOME}/.local/bin${PATH:+:}${PATH}"
+ export PATH="${HOME}/.local/bin${PATH:+:}${PATH}"
- On **Debian** and **Ubuntu**:
- .. code-block:: sh
+ .. code-block:: shell
sudo apt install doxygen graphviz python3-pip
python3 -m pip install --user -r docs/requirements.txt
- On **CentOS** and **Fedora**:
- .. code-block:: sh
+ .. code-block:: shell
sudo dnf install doxygen graphviz python3-pip
python3 -m pip install --user -r docs/requirements.txt
- On **macOS**:
- .. code-block:: sh
+ .. code-block:: shell
brew install doxygen graphviz
python3 -m pip install --user -r docs/requirements.txt
- On **FreeBSD**:
- .. code-block:: sh
+ .. code-block:: shell
sudo pkg install doxygen graphviz py39-sphinx
-Build
------
+Building
+--------
.. note::
- These are instructions for regular builds of ndn-cxx (release mode). If you are
- planning to develop the ndn-cxx code itself, you should do a :ref:`Development build`.
+ These are the instructions for a regular build of ndn-cxx (release mode). If you are planning
+ to develop or modify the ndn-cxx code itself, you should do a :ref:`Development build`.
To build in a terminal, change directory to the ndn-cxx root, then enter:
-.. code-block:: sh
+.. code-block:: shell
./waf configure
./waf
@@ -141,7 +137,7 @@
By default, only the shared variant of the ndn-cxx library will be built. To build the
static library, pass ``--enable-static`` to the ``./waf configure`` command:
-.. code-block:: sh
+.. code-block:: shell
./waf configure --enable-static
@@ -149,25 +145,25 @@
additional ``--disable-shared`` option. Note that at least one variant of the library
needs to be enabled.
-.. code-block:: sh
+.. code-block:: shell
./waf configure --enable-static --disable-shared
On Linux, it is necessary to run the following command after the shared library has
been installed:
-.. code-block:: sh
+.. code-block:: shell
sudo ldconfig
-.. note::
+.. tip::
On Linux, when the library is installed in a non-default location (generally, not in
``/usr/lib`` or ``/usr/local/lib``), the following additional actions may be necessary.
The library installation path should be added to ``/etc/ld.so.conf`` or to
``/etc/ld.so.conf.d/*.conf`` before running ``ldconfig``. For example:
- .. code-block:: sh
+ .. code-block:: shell
echo /usr/local/lib64 | sudo tee /etc/ld.so.conf.d/ndn-cxx.conf
sudo ldconfig
@@ -175,7 +171,7 @@
Alternatively, the ``LD_LIBRARY_PATH`` environment variable can be set to point to
the installation directory of the shared library:
- .. code-block:: sh
+ .. code-block:: shell
export LD_LIBRARY_PATH=/usr/local/lib64
@@ -190,7 +186,8 @@
``PKG_CONFIG_PATH`` is configured properly (or if ``<LIBDIR>/pkgconfig`` is a default
search path), the command ``pkgconf --cflags --libs libndn-cxx`` will return all
necessary compile and link flags for the ndn-cxx library.
-- ``<BINDIR>/ndnsec``: command-line tool to manage NDN keys and certificates.
+- ``<BINDIR>/ndnsec``: command-line tool to manage NDN keys and certificates used by
+ ndn-cxx applications.
- ``<BINDIR>/ndnsec-*``: convenience aliases for ``ndnsec`` tools.
If configured with tests (``./waf configure --with-tests``), the above commands
@@ -204,13 +201,13 @@
available memory divided by 1.5 GB (e.g., ``./waf -j2`` for 3 GB of memory). This
should avoid memory thrashing and result in faster compilation.
-Build with examples
--------------------
+Building with examples
+----------------------
By default, the examples in the ``examples/`` directory will not be built. To enable
them, pass ``--with-examples`` during the configuration step:
-.. code-block:: sh
+.. code-block:: shell
./waf configure --with-examples
./waf
@@ -219,7 +216,7 @@
To run the examples:
-.. code-block:: sh
+.. code-block:: shell
# trivial producer app
./build/examples/producer
@@ -233,7 +230,7 @@
If you want to make a new sample application, just create a ``.cpp`` file inside the
``examples/`` directory and it will be compiled during the next run of ``./waf``:
-.. code-block:: sh
+.. code-block:: shell
cp examples/consumer.cpp examples/my-new-app.cpp
... # edit examples/my-new-app.cpp with your preferred editor
@@ -242,39 +239,12 @@
sudo ldconfig # on Linux only
./build/examples/my-new-app
-Debug symbols
--------------
-
-The default compiler flags include debug symbols in binaries. This should provide
-more meaningful debugging information if ndn-cxx or your application crashes.
-
-If this is not desired, the default flags can be overridden to disable debug symbols.
-The following example shows how to completely disable debug symbols and configure
-ndn-cxx to be installed into ``/usr`` with configuration in the ``/etc`` directory.
-
-.. code-block:: sh
-
- CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
- ./waf
- sudo ./waf install
-
-Customizing the compiler
-------------------------
-
-To build ndn-cxx with a different compiler (rather than the platform default), set the
-``CXX`` environment variable to point to the compiler binary. For example, to build
-with clang on Linux, use the following:
-
-.. code-block:: sh
-
- CXX=clang++ ./waf configure
-
Building the documentation
--------------------------
Tutorials and API documentation can be built using the following commands:
-.. code-block:: sh
+.. code-block:: shell
# Full set of documentation (tutorials + API) in build/docs
./waf docs
@@ -294,6 +264,33 @@
For further details, please refer to ``./waf --help``.
+Debug symbols
+-------------
+
+The default compiler flags include debug symbols in binaries. This should provide
+more meaningful debugging information if ndn-cxx or your application crashes.
+
+If this is not desired, the default flags can be overridden to disable debug symbols.
+The following example shows how to completely disable debug symbols and configure
+ndn-cxx to be installed into ``/usr`` with configuration in the ``/etc`` directory.
+
+.. code-block:: shell
+
+ CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
+ ./waf
+ sudo ./waf install
+
+Customizing the compiler
+------------------------
+
+To build ndn-cxx with a different compiler (rather than the platform default), set the
+``CXX`` environment variable to point to the compiler binary. For example, to build
+with clang on Linux, use the following:
+
+.. code-block:: shell
+
+ CXX=clang++ ./waf configure
+
.. _Development build:
Development build
@@ -301,7 +298,7 @@
The following is the suggested build procedure for development builds:
-.. code-block:: sh
+.. code-block:: shell
./waf configure --debug --with-tests
./waf
@@ -312,7 +309,7 @@
will be treated as errors. This default behavior can be overridden by setting the
``CXXFLAGS`` environment variable before running ``./waf configure``, for example:
-.. code-block:: sh
+.. code-block:: shell
CXXFLAGS="-O1 -g3 -Wall" ./waf configure --debug --with-tests
./waf