docs: sync sphinx build config with ndn-cxx, improve README.md
Replace custom redmine_issue extension with sphinx.ext.extlinks
Change-Id: Ie6995fd418e4e355cc193b68423899fc029d93ce
diff --git a/.waf-tools/sphinx_build.py b/.waf-tools/sphinx_build.py
index e61da6e..b44a54f 100644
--- a/.waf-tools/sphinx_build.py
+++ b/.waf-tools/sphinx_build.py
@@ -44,28 +44,28 @@
task.inputs.append(conf)
confdir = conf.parent.abspath()
- buildername = getattr(self, "builder", "html")
- srcdir = getattr(self, "srcdir", confdir)
- outdir = self.path.find_or_declare(getattr(self, "outdir", buildername)).get_bld()
- doctreedir = getattr(self, "doctreedir", os.path.join(outdir.abspath(), ".doctrees"))
+ buildername = getattr(self, 'builder', 'html')
+ srcdir = getattr(self, 'srcdir', confdir)
+ outdir = self.path.find_or_declare(getattr(self, 'outdir', buildername)).get_bld()
+ doctreedir = getattr(self, 'doctreedir', os.path.join(outdir.abspath(), '.doctrees'))
task.env['BUILDERNAME'] = buildername
task.env['SRCDIR'] = srcdir
task.env['DOCTREEDIR'] = doctreedir
task.env['OUTDIR'] = outdir.abspath()
- task.env['VERSION'] = "version=%s" % self.VERSION
- task.env['RELEASE'] = "release=%s" % self.VERSION
+ task.env['VERSION'] = 'version=%s' % self.version
+ task.env['RELEASE'] = 'release=%s' % getattr(self, 'release', self.version)
import imp
confData = imp.load_source('sphinx_conf', conf.abspath())
- if buildername == "man":
+ if buildername == 'man':
for i in confData.man_pages:
target = outdir.find_or_declare('%s.%d' % (i[1], i[4]))
task.outputs.append(target)
if self.install_path:
- self.bld.install_files("%s/man%d/" % (self.install_path, i[4]), target)
+ self.bld.install_files('%s/man%d/' % (self.install_path, i[4]), target)
else:
task.outputs.append(outdir)
diff --git a/INSTALL.md b/INSTALL.md
deleted file mode 100644
index 7ea2ce3..0000000
--- a/INSTALL.md
+++ /dev/null
@@ -1,5 +0,0 @@
-NFD Installation Instructions
-=============================
-
-See [`docs/INSTALL.rst`](https://github.com/named-data/NFD/blob/master/docs/INSTALL.rst)
-for detailed NFD installation instructions.
diff --git a/README-dev.md b/README-dev.md
index c009d01..69b3a35 100644
--- a/README-dev.md
+++ b/README-dev.md
@@ -2,20 +2,25 @@
========================
If you are new to the NDN software community, please read the
-[Contributor's Guide](https://github.com/named-data/NFD/blob/master/CONTRIBUTING.md)
+[Contributor's Guide](https://github.com/named-data/NFD/blob/master/CONTRIBUTING.md).
-Requirements
-------------
+Code style
+----------
-Contributions to NFD must be licensed under GPL 3.0 or compatible license. If you are
-choosing GPL 3.0, please use the following license boilerplate in all `.hpp` and `.cpp`
-files:
+NFD code is subject to [NFD code style](https://redmine.named-data.net/projects/nfd/wiki/CodeStyle).
+
+Licensing
+---------
+
+Contributions to NFD must be licensed under the GPL 3.0 or compatible license. If you
+are choosing GPL 3.0, please use the following license boilerplate in all `.hpp` and
+`.cpp` files:
Include the following license boilerplate into all `.hpp` and `.cpp` files:
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
- * Copyright (c) [Year(s)], [Copyright Holder(s)].
+ * Copyright (c) [Year(s)], [Copyright Holder(s)].
*
* This file is part of NFD (Named Data Networking Forwarding Daemon).
* See AUTHORS.md for complete list of NFD authors and contributors.
@@ -35,32 +40,26 @@
If you are affiliated to an NSF-supported NDN project institution, please use the [NDN Team License
Boilerplate](https://redmine.named-data.net/projects/nfd/wiki/NDN_Team_License_Boilerplate_(NFD)).
-Recommendations
----------------
-
-NFD code is subject to NFD [code style](https://redmine.named-data.net/projects/nfd/wiki/CodeStyle).
-
-
-Running unit-tests
+Running unit tests
------------------
To run unit tests, NFD needs to be configured and build with unit test support:
- ./waf configure --with-tests
+ ./waf configure --with-tests # --debug is also strongly recommended while developing
./waf
-The simplest way to run tests, is just to run the compiled binary without any parameters:
+The simplest way to run the tests is to launch the compiled binary without any parameters:
# Run core tests
./build/unit-tests-core
- # Run NFD daemon tests
+ # Run NFD daemon tests
./build/unit-tests-daemon
# Run NFD RIB management tests
./build/unit-tests-rib
-However, [Boost.Test framework](https://www.boost.org/doc/libs/1_58_0/libs/test/doc/html/index.html)
+[Boost.Test framework](https://www.boost.org/doc/libs/1_58_0/libs/test/doc/html/index.html)
is very flexible and allows a number of run-time customization of what tests should be run.
For example, it is possible to choose to run only a specific test suite, only a specific
test case within a suite, or specific test cases within specific test suites:
@@ -76,8 +75,8 @@
By default, Boost.Test framework will produce verbose output only when a test case fails.
If it is desired to see verbose output (result of each test assertion), add `-l all`
-option to `./build/unit-tests` command. To see test progress, you can use `-l test_suite`
-or `-p` to show progress bar:
+option to `./build/unit-tests` command. To see test progress, you can use `-l test_suite`,
+or `-p` to show a progress bar:
# Show report all log messages including the passed test notification
./build/unit-tests-daemon -l all
@@ -91,7 +90,7 @@
# Show progress bar
./build/unit-tests-core -p
-There are many more command line options available, information about
-which can be obtained either from the command line using `--help`
-switch, or online on [Boost.Test library](https://www.boost.org/doc/libs/1_58_0/libs/test/doc/html/index.html)
+There are many more command line options available, information about which can be obtained
+either from the command line using `--help` switch, or online on
+[Boost.Test library](https://www.boost.org/doc/libs/1_58_0/libs/test/doc/html/index.html)
website.
diff --git a/README.md b/README.md
index c6eff54..e603989 100644
--- a/README.md
+++ b/README.md
@@ -1,38 +1,15 @@
-NFD - Named Data Networking Forwarding Daemon
-=============================================
+# NFD - Named Data Networking Forwarding Daemon
+
[](https://travis-ci.org/named-data/NFD)
-
-For complete documentation, including step-by-step installation instructions and
-tutorials, please visit the [NFD homepage](https://named-data.net/doc/NFD/).
-
-If you are new to the NDN software community, please read README-dev.md and the
-[Contributor's Guide](https://github.com/named-data/NFD/blob/master/CONTRIBUTING.md).
+
## Overview
NFD is a network forwarder that implements and evolves together with the Named Data
-Networking (NDN) [protocol](https://named-data.net/doc/ndn-tlv/). After the initial
-release, NFD will become a core component of the
-[NDN Platform](https://named-data.net/codebase/platform/) and will follow the same release
-cycle.
-
-NFD is an open and free software package licensed under GPL 3.0 license and is the
-centerpiece of our committement to making NDN's core technology open and free to all
-Internet users and developers. For more information about the licensing details and
-limitation, refer to
-[`COPYING.md`](https://github.com/named-data/NFD/blob/master/COPYING.md).
-
-NFD is developed by a community effort. Although the first release was mostly done by the
-members of [NSF-sponsored NDN project team](https://named-data.net/project/participants/),
-it already contains significant contributions from people outside the project team (for
-more details, refer to
-[`AUTHORS.md`](https://github.com/named-data/NFD/blob/master/AUTHORS.md)). We strongly
-encourage participation from all interested parties, since broader community support is
-key for NDN to succeed as a new Internet architecture. Bug reports and feedback are
-highly appreciated and can be made through
-[Redmine site](https://redmine.named-data.net/projects/nfd) and the
-[ndn-interest mailing list](http://www.lists.cs.ucla.edu/mailman/listinfo/ndn-interest).
+Networking (NDN) [protocol](https://named-data.net/doc/NDN-packet-spec/current/).
+Since the initial public release in 2014, NFD has been a core component of the
+[NDN Platform](https://named-data.net/codebase/platform/).
The main design goal of NFD is to support diverse experimentation of NDN technology. The
design emphasizes *modularity* and *extensibility* to allow easy experiments with new
@@ -45,3 +22,33 @@
up with the NDN protocol spec, and addition of other new features. We hope to keep the
modular framework stable and lean, allowing researchers to implement and experiment with
various features, some of which may eventually work into the protocol spec.
+
+## Documentation
+
+See [`docs/INSTALL.rst`](docs/INSTALL.rst) for compilation and installation instructions.
+
+Extensive documentation is available on NFD's [homepage](https://named-data.net/doc/NFD/).
+
+## Reporting bugs
+
+Bug reports and feedback are highly appreciated and can be submitted through the
+[NFD issue tracker](https://redmine.named-data.net/projects/nfd/issues) or the
+[ndn-interest mailing list](http://www.lists.cs.ucla.edu/mailman/listinfo/ndn-interest).
+
+## Contributing
+
+NFD is developed by a community effort. Although the first release was mostly done by the
+members of [NSF-sponsored NDN project team](https://named-data.net/project/participants/),
+it already contains significant contributions from people outside the project team (see
+[`AUTHORS.md`](AUTHORS.md)). We strongly encourage participation from all interested parties,
+since broader community support is key for NDN to succeed as a new Internet architecture.
+
+If you are new to the NDN software community, please read [`README-dev.md`](README-dev.md)
+and the [Contributor's Guide](CONTRIBUTING.md) to get started.
+
+## License
+
+NFD is an open and free software package licensed under the GPL version 3 and is the
+centerpiece of our committement to making NDN's core technology open and free to all
+Internet users and developers. For more information about the licensing details and
+limitations, refer to [`COPYING.md`](COPYING.md).
diff --git a/docs/conf.py b/docs/conf.py
index 99b993a..60dd74f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,39 +1,53 @@
# -*- coding: utf-8 -*-
#
-# NFD documentation build configuration file, created by
-# sphinx-quickstart on Wed Mar 7 19:23:56 2018.
+# Configuration file for the Sphinx documentation builder.
#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
+# 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
-import datetime
-import os
-import sys
+# -- Path setup --------------------------------------------------------------
# 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('.'))
+#
+import os
+import sys
+# sys.path.insert(0, os.path.abspath('.'))
-# -- General configuration ------------------------------------------------
+# -- Project information -----------------------------------------------------
+
+project = u'Named Data Networking Forwarding Daemon (NFD)'
+copyright = u'Copyright © 2014-2019 Named Data Networking Project.'
+author = u'Named Data Networking Project'
+
+# The short X.Y version
+#version = ''
+
+# The full version, including alpha/beta/rc tags
+#release = ''
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%Y-%m-%d'
+
+
+# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
-# needs_sphinx = '1.0'
+needs_sphinx = '1.1'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
+ 'sphinx.ext.extlinks',
'sphinx.ext.todo',
- 'redmine_issue'
]
def addExtensionIfExists(extension):
@@ -41,10 +55,8 @@
__import__(extension)
extensions.append(extension)
except ImportError:
- sys.stderr.write("Extension '%s' in not available. "
+ sys.stderr.write("Extension '%s' not found. "
"Some documentation may not build correctly.\n" % extension)
- sys.stderr.write("To install, use \n"
- " sudo pip install %s\n" % extension.replace('.', '-'))
if sys.version_info[0] >= 3:
addExtensionIfExists('sphinxcontrib.doxylink')
@@ -53,65 +65,25 @@
# if os.getenv('GOOGLE_ANALYTICS', None):
# addExtensionIfExists('sphinxcontrib.googleanalytics')
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
-
# The master toctree document.
master_doc = 'index'
-# General information about the project.
-project = u'NFD - Named Data Networking Forwarding Daemon'
-copyright = u'2014-%d, Named Data Networking Project' % datetime.date.today().year
-author = u'Named Data Networking Project'
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-# version = u''
-# The full version, including alpha/beta/rc tags.
-# release = u''
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
-# This patterns also effect to html_static_path and html_extra_path
+# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
-
-
-# -- Options for HTML output ----------------------------------------------
+# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
-# html_theme = 'alabaster'
html_theme = 'named_data_theme'
-# Theme options are theme-specific and customize the look and feel of a theme
-# further. For a list of options available for each theme, see the
-# documentation.
-#
-# html_theme_options = {}
-
# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = ['.']
@@ -121,13 +93,7 @@
html_static_path = ['_static']
-# -- Options for HTMLHelp output ------------------------------------------
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'nfd-docs'
-
-
-# -- Options for LaTeX output ---------------------------------------------
+# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
@@ -151,47 +117,46 @@
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
- ('index', 'nfd-docs.tex', u'NFD - Named Data Networking Forwarding Daemon Documentation',
- u'Named Data Networking Project', 'manual'),
+ ('index', 'nfd-docs.tex', u'Named Data Networking Forwarding Daemon (NFD)',
+ author, 'manual'),
]
-# -- Options for manual page output ---------------------------------------
+# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- ('manpages/nfd', 'nfd', u'Named Data Networking Forwarding Daemon', '', 1),
- ('manpages/nfdc', 'nfdc', u'Interact with NFD management', '', 1),
- ('manpages/nfdc-status', 'nfdc-status', u'Show NFD status', '', 1),
- ('manpages/nfdc-face', 'nfdc-face', u'Show and manipulate NFD faces', '', 1),
- ('manpages/nfdc-route', 'nfdc-route', u'Show and manipulate NFD routes', '', 1),
- ('manpages/nfdc-cs', 'nfdc-cs', u'Show and manipulate NFD Content Store', '', 1),
- ('manpages/nfdc-strategy', 'nfdc-strategy', u'Show and manipulate NFD strategy choices', '', 1),
- ('manpages/nfd-status', 'nfd-status', u'Comprehensive report of NFD status', '', 1),
- ('manpages/nfd-status-http-server', 'nfd-status-http-server', u'NFD status HTTP server', '', 1),
- ('manpages/ndn-autoconfig-server', 'ndn-autoconfig-server', u'NDN auto-configuration server', '', 1),
- ('manpages/ndn-autoconfig', 'ndn-autoconfig', u'NDN auto-configuration client', '', 1),
- ('manpages/ndn-autoconfig.conf', 'ndn-autoconfig.conf', u'NDN auto-configuration client configuration file', '', 5),
- ('manpages/nfd-autoreg', 'nfd-autoreg', u'NFD auto-registration server', '', 1),
- ('manpages/nfd-asf-strategy', 'nfd-asf-strategy', u'NFD ASF strategy', '', 7),
+ ('manpages/nfd', 'nfd', 'the Named Data Networking Forwarding Daemon', [], 1),
+ ('manpages/nfdc', 'nfdc', 'interact with NFD management from the command line', [], 1),
+ ('manpages/nfdc-status', 'nfdc-status', 'show NFD status', [], 1),
+ ('manpages/nfdc-face', 'nfdc-face', 'show and manipulate NFD\'s faces', [], 1),
+ ('manpages/nfdc-route', 'nfdc-route', 'show and manipulate NFD\'s routes', [], 1),
+ ('manpages/nfdc-cs', 'nfdc-cs', 'show and manipulate NFD\'s Content Store', [], 1),
+ ('manpages/nfdc-strategy', 'nfdc-strategy', 'show and manipulate NFD\'s strategy choices', [], 1),
+ ('manpages/nfd-status', 'nfd-status', 'show a comprehensive report of NFD\'s status', [], 1),
+ ('manpages/nfd-status-http-server', 'nfd-status-http-server', 'NFD status HTTP server', [], 1),
+ ('manpages/ndn-autoconfig-server', 'ndn-autoconfig-server', 'auto-configuration server for NDN', [], 1),
+ ('manpages/ndn-autoconfig', 'ndn-autoconfig', 'auto-configuration client for NDN', [], 1),
+ ('manpages/ndn-autoconfig.conf', 'ndn-autoconfig.conf', 'configuration file for ndn-autoconfig', [], 5),
+ ('manpages/nfd-autoreg', 'nfd-autoreg', 'NFD automatic prefix registration daemon', [], 1),
+ ('manpages/nfd-asf-strategy', 'nfd-asf-strategy', 'NFD ASF strategy', [], 7),
]
+# If true, show URL addresses after external links.
+#man_show_urls = True
-# -- Options for Texinfo output -------------------------------------------
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-# dir menu entry, description, category)
-texinfo_documents = []
-
+# -- Custom options ----------------------------------------------------------
doxylink = {
- 'nfd' : ('NFD.tag', 'doxygen/'),
+ 'nfd': ('NFD.tag', 'doxygen/'),
+}
+
+extlinks = {
+ 'issue': ('https://redmine.named-data.net/issues/%s', 'issue #'),
}
if os.getenv('GOOGLE_ANALYTICS', None):
googleanalytics_id = os.environ['GOOGLE_ANALYTICS']
googleanalytics_enabled = True
-
-redmine_project_url = 'https://redmine.named-data.net/'
diff --git a/docs/redmine_issue.py b/docs/redmine_issue.py
deleted file mode 100644
index 0df2b1f..0000000
--- a/docs/redmine_issue.py
+++ /dev/null
@@ -1,70 +0,0 @@
-# -*- Mode: python; py-indent-offset: 4; indent-tabs-mode: nil; coding: utf-8; -*-
-# Based on http://doughellmann.com/2010/05/09/defining-custom-roles-in-sphinx.html
-
-"""Integration of Sphinx with Redmine.
-"""
-
-from docutils import nodes, utils
-from docutils.parsers.rst.roles import set_classes
-
-def redmine_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
- """Link to a Redmine issue.
-
- Returns 2 part tuple containing list of nodes to insert into the
- document and a list of system messages. Both are allowed to be
- empty.
-
- :param name: The role name used in the document.
- :param rawtext: The entire markup snippet, with role.
- :param text: The text marked with the role.
- :param lineno: The line number where rawtext appears in the input.
- :param inliner: The inliner instance that called us.
- :param options: Directive options for customization.
- :param content: The directive content for customization.
- """
- try:
- issue_num = int(text)
- if issue_num <= 0:
- raise ValueError
- except ValueError:
- msg = inliner.reporter.error(
- 'Redmine issue number must be a number greater than or equal to 1; '
- '"%s" is invalid.' % text, line=lineno)
- prb = inliner.problematic(rawtext, rawtext, msg)
- return [prb], [msg]
- app = inliner.document.settings.env.app
- node = make_link_node(rawtext, app, 'issues', str(issue_num), options)
- return [node], []
-
-def make_link_node(rawtext, app, type, slug, options):
- """Create a link to a Redmine resource.
-
- :param rawtext: Text being replaced with link node.
- :param app: Sphinx application context
- :param type: Link type (issue, changeset, etc.)
- :param slug: ID of the thing to link to
- :param options: Options dictionary passed to role func.
- """
- #
- try:
- base = app.config.redmine_project_url
- if not base:
- raise AttributeError
- except AttributeError:
- raise ValueError('redmine_project_url configuration value is not set')
- #
- slash = '/' if base[-1] != '/' else ''
- ref = base + slash + type + '/' + slug + '/'
- set_classes(options)
- node = nodes.reference(rawtext, 'Issue #' + utils.unescape(slug), refuri=ref,
- **options)
- return node
-
-def setup(app):
- """Install the plugin.
-
- :param app: Sphinx application context.
- """
- app.add_role('issue', redmine_role)
- app.add_config_value('redmine_project_url', None, 'env')
- return
diff --git a/wscript b/wscript
index d04d3d9..90f7536 100644
--- a/wscript
+++ b/wscript
@@ -220,9 +220,10 @@
builder='man',
config='docs/conf.py',
outdir='docs/manpages',
- source=bld.path.ant_glob('docs/manpages/**/*.rst'),
+ source=bld.path.ant_glob('docs/manpages/*.rst'),
install_path='${MANDIR}',
- VERSION=VERSION)
+ version=VERSION_BASE,
+ release=VERSION)
bld.symlink_as('${MANDIR}/man1/nfdc-channel.1', 'nfdc-face.1')
bld.symlink_as('${MANDIR}/man1/nfdc-fib.1', 'nfdc-route.1')
bld.symlink_as('${MANDIR}/man1/nfdc-register.1', 'nfdc-route.1')
@@ -281,7 +282,8 @@
config='docs/conf.py',
outdir='docs',
source=bld.path.ant_glob('docs/**/*.rst'),
- VERSION=VERSION)
+ version=VERSION_BASE,
+ release=VERSION)
def version(ctx):
# don't execute more than once