docs: Prepare release notes for version 0.3.0
Change-Id: If0ae14cbf97ee3d9b92a3467d0b6592c10e66698
Refs: #2462, #2352, #2209
diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst
index e04ee48..3d94d74 100644
--- a/docs/INSTALL.rst
+++ b/docs/INSTALL.rst
@@ -243,6 +243,17 @@
./waf
sudo ./waf install
+Customize Compiler
+~~~~~~~~~~~~~~~~~~
+
+To customize compiler, set ``CXX`` environment variable to point to compiler binary and, in
+some case, specify type of the compiler using ``--check-cxx-compiler``. For example, when
+using clang compiler on Linux system, use the following:
+
+::
+
+ CXX=clang++ ./waf configure --check-cxx-compiler=clang++
+
Building documentation
~~~~~~~~~~~~~~~~~~~~~~
@@ -358,10 +369,9 @@
Sample applications:
-- `Simple examples in ndn-cxx
- library <http://named-data.net/doc/ndn-cxx/current/examples.html>`__.
- If you have installed ndn-cxx from source, you already have compiled
- these:
+- `Simple examples in ndn-cxx library <http://named-data.net/doc/ndn-cxx/current/examples.html>`_
+
+ If you have installed ndn-cxx from source, you already have compiled these:
+ examples/producer
+ examples/consumer
@@ -370,18 +380,16 @@
+ tools/ndncatchunks3
+ tools/ndnputchunks3
-- `Introductory examples of
- NDN-CCL <http://redmine.named-data.net/projects/nfd/wiki/Getting_Started_-_Common_Client_Libraries#Install-the-Common-Client-Library>`__
+- `Introductory examples of NDN-CCL
+ <http://redmine.named-data.net/projects/application-development-documentation-guides/wiki/Step-By-Step_-_Common_Client_Libraries>`_
Real applications and libraries:
+ `ndn-tlv-ping - Reachability Testing Tool for NDN
- <https://github.com/named-data/ndn-tlv-ping>`__
- + `ndn-traffic-generator - Traffic Generator For
- NDN <https://github.com/named-data/ndn-traffic-generator>`__
- + `repo-ng - Next generation of NDN
- repository <https://github.com/named-data/repo-ng>`__
- + `ChronoChat - Multi-user NDN chat
- application <https://github.com/named-data/ChronoChat>`__
- + `ChronoSync - Sync library for multiuser realtime applications for
- NDN <https://github.com/named-data/ChronoSync>`__
+ <https://github.com/named-data/ndn-tlv-ping>`_
+ + `ndn-traffic-generator - Traffic Generator For NDN
+ <https://github.com/named-data/ndn-traffic-generator>`_
+ + `repo-ng - Next generation of NDN repository <https://github.com/named-data/repo-ng>`_
+ + `ChronoChat - Multi-user NDN chat application <https://github.com/named-data/ChronoChat>`_
+ + `ChronoSync - Sync library for multiuser realtime applications for NDN
+ <https://github.com/named-data/ChronoSync>`_
diff --git a/docs/RELEASE_NOTES.rst b/docs/RELEASE_NOTES.rst
index bfb47b9..b5376ab 100644
--- a/docs/RELEASE_NOTES.rst
+++ b/docs/RELEASE_NOTES.rst
@@ -3,6 +3,259 @@
NFD Release Notes
=================
+NFD version 0.3.0 (changes since version 0.2.0)
+-----------------------------------------------
+
+Release date: February 2, 2015
+
+
+New features:
+^^^^^^^^^^^^^
+
+- **Build**
+
+ + The code now requires C++11. The minimum supported gcc version is 4.6, as earlier versions
+ do not have proper support for C++11 features.
+
+- **Faces**
+
+ + Enable detection of WebSocket connection failures using ping/pong messages (:issue:`1903`)
+
+ + In EthernetFace:
+
+ * Avoid putting the NIC in promiscuous mode if possible (:issue:`1278`)
+
+ * Report packets dropped by the kernel if debug is enabled (:issue:`2441`)
+
+ * Integrate NDNLP fragmentation (:issue:`1209`)
+
+- **Forwarding**
+
+ + Strategy versioning (:issue:`1893`)
+
+ + New Dead Nonce List table to supplement PIT for loop detection (:issue:`1953`)
+
+ + Abstract retransmission suppression logic (:issue:`2377`)
+
+ + New forwarding strategy for access router (:issue:`1999`)
+
+- **Management**
+
+ + Add config file-based strategy selection (:issue:`2053`)
+
+ The sample config file now includes strategy selection for ``/``, ``/localhost``,
+ ``/localhost/nfd``, and ``/ndn/broadcast`` namespaces as follows:
+
+ ::
+
+ tables
+ {
+ ...
+ strategy_choice
+ {
+ / /localhost/nfd/strategy/best-route
+ /localhost /localhost/nfd/strategy/broadcast
+ /localhost/nfd /localhost/nfd/strategy/best-route
+ /ndn/broadcast /localhost/nfd/strategy/broadcast
+ }
+ }
+
+ + Implement Query Operation in FaceManager (:issue:`1993`)
+
+ + FaceManager now responds with producer-generated NACK when query is invalid (:issue:`1993`)
+
+ + Add functionality for automatic remote prefix registration (:issue:`2056`)
+
+ + Only canonical FaceUri are allowed in faces/create commands (:issue:`1910`)
+
+- **Tables**
+
+ + StrategyInfoHost can now store multiple StrategyInfo of distinct types (:issue:`2240`)
+
+ + Enable iteration over PIT and CS entries (:issue:`2339`)
+
+ + Allow predicate to be specified in Measurements::findLongestPrefixMatch (:issue:`2314`)
+
+ + Calculate the implicit digest of Data packets in CS only when necessary (:issue:`1706`)
+
+- **Tools**
+
+ + Publish ``/localhop/ndn-autoconf/routable-prefixes`` from ``ndn-autoconfig-server``
+ (:issue:`1954`)
+
+ + Display detailed NFD software verion in ``nfd-status-http-server`` and ``nfd-status``
+ (:issue:`1916`)
+
+ + ``nfdc`` now accepts FaceUri in all commands (:issue:`1995`)
+
+ + Add daemon mode for ``ndn-autoconfig`` to re-run detection when connectivity changes
+ (:issue:`2417`)
+
+- **Core**
+
+ + New scheduler::ScopedEventId class to automatically handle scheduled event lifetime
+ (:issue:`2295`)
+
+Updates and bug fixes:
+^^^^^^^^^^^^^^^^^^^^^^
+
+- **Documentation**
+
+ + NFD Developer's guide has been updated to reflect changes in the codebase
+
+ + Installation instruction updates
+
+ + Update of config file instructions for disabling unix sockets (:issue:`2190`)
+
+- **Core**
+
+ + Use implementations moved to ndn-cxx library
+
+ + Use Signal from ndn-cxx (:issue:`2272`, :issue:`2300`)
+
+ + use ethernet::Address from ndn-cxx (:issue:`2142`)
+
+ + Use MAX_NDN_PACKET_SIZE constant from ndn-cxx (:issue:`2099`)
+
+ + Use DEFAULT_INTEREST_LIFETIME from ndn-cxx (:issue:`2202`)
+
+ + Use FaceUri from ndn-cxx (:issue:`2143`)
+
+ + Use DummyClientFace from ndn-cxx (:issue:`2186`)
+
+ + Use ndn::dns from ndn-cxx (:issue:`2207`)
+
+ + Move Network class implementation from ``tools/`` to ``core/``
+
+ + Ignore non-Ethernet ``AF_LINK`` addresses when enumerating NICs on OSX and other BSD systems
+
+ + Fix bug on not properly setting FreshnessPeriod inside SegmentPublisher (:issue:`2438`)
+
+- **Faces**
+
+ + Fix spurious assertion failure in StreamFace (:issue:`1856`)
+
+ + Update websocketpp submodule (:issue:`1903`)
+
+ + Replace FaceFlags with individual fields (:issue:`1992`)
+
+ + Drop WebSocket message if the size is larger than maximum NDN packet size (:issue:`2081`)
+
+ + Make EthernetFace more robust against errors (:issue:`1984`)
+
+ + Prevent potential infinite loop in TcpFactory and UdpFactory (:issue:`2292`)
+
+ + Prevent crashes when attempting to create a UdpFace over a half-working connection
+ (:issue:`2311`)
+
+ + Support MTU larger than 1500 in EthernetFace (for jumbo frames) (:issue:`2305`)
+
+ + Re-enable EthernetFace on OS X platform with boost >=1.57.0 (:issue:`1922`)
+
+ + Fix ``ioctl()`` calls on platforms where libpcap uses ``/dev/bpf*`` (:issue:`2327`)
+
+ + Fix overhead estimation in NDNLP slicer (:issue:`2317`)
+
+ + Replace usage of deprecated EventEmitter with Signal in Face abstractions (:issue:`2300`)
+
+ + Fix NDNLP PartialMessage cleanup scheduling (:issue:`2414`)
+
+ + Remove unnecessary use of DNS resolver in (Udp|Tcp|WebSocket)Factory (:issue:`2422`)
+
+- **Forwarding**
+
+ + Updates related to NccStrategy
+
+ * Fix to prevent remembering of suboptimal upstreams (:issue:`1961`)
+
+ * Optimizing FwNccStrategy/FavorRespondingUpstream test case (:issue:`2037`)
+
+ * Proper detection for new PIT entry (:issue:`1971`)
+
+ * Use UnitTestTimeFixture in NCC test case (:issue:`2163`)
+
+ * Fix loop back to sole downstream (:issue:`1998`)
+
+ + Updates related to BestRoute strategy
+
+ + Redesign best-route v2 strategy test case (:issue:`2126`)
+
+ + Fix clang compilation error in best-route v2 test case (:issue:`2179`)
+
+ + Use UnitTestClock in BestRouteStrategy2 test (:issue:`2160`)
+
+ + Allow strategies limited access to FaceTable (:issue:`2272`)
+
+- **Tables**
+
+ + Ensure that eviction of unsolicited Data is done in FIFO order (:issue:`2043`)
+
+ + Simplify table implementations with C++11 features (:issue:`2100`)
+
+ + Fix issue with Fib::removeNextHopFromAllEntries invalidating NameTree iterator
+ (:issue:`2177`)
+
+ + Replace deprecated EventEmitter with Signal in FaceTable (:issue:`2272`)
+
+ + Refactored implementation of ContentStore based on std::set (:issue:`2254`)
+
+- **Management**
+
+ + Allow omitted FaceId in faces/create command (:issue:`2031`)
+
+ + Avoid deprecated ``ndn::nfd::Controller(Face&)`` constructor (:issue:`2039`)
+
+ + Enable check of command length before accessing verb (:issue:`2151`)
+
+ + Rename FaceEntry to Route (:issue:`2159`)
+
+ + Insert RIB command prefixes into RIB (:issue:`2312`)
+
+- **Tools**
+
+ + Display face attribute fields instead of FaceFlags in ``nfd-status`` and
+ ``nfd-status-http-server`` output (:issue:`1991`)
+
+ + Fix ``nfd-status-http-server`` hanging when nfd-status output is >64k (:issue:`2121`)
+
+ + Ensure that ``ndn-autoconfig`` canonizes FaceUri before sending commands to NFD
+ (:issue:`2387`)
+
+ + Refactored ndn-autoconfig implementation (:issue:`2421`)
+
+ + ndn-autoconfig will now register also ``/localhop/nfd`` prefix towards the hub (:issue:`2416`)
+
+- **Tests**
+
+ + Use UnitTestClock in Forwarder persistent loop test case (:issue:`2162`)
+
+ + Use LimitedIo in FwForwarder/SimpleExchange test case (:issue:`2161`)
+
+- **Build**
+
+ + Fix build error with python3 (:issue:`1302`)
+
+ + Embed CI build and test running script
+
+ + Properly disable assertions in release builds (:issue:`2139`)
+
+ + Embed setting of ``PKG_CONFIG_PATH`` variable to commonly used values (:issue:`2178`)
+
+ + Add conditional compilation for NetworkInterface and PrivilegeHelper
+
+ + Support tools with multiple translation units (:issue:`2344`)
+
+Removals
+^^^^^^^^
+
+- Remove ``listen`` option from unix channel configuration (:issue:`2188`)
+
+- Remove usage of deprecated ``MetaInfo::TYPE_*`` constants (:issue:`2128`)
+
+- Eliminate MapValueIterator in favor of ``boost::adaptors::map_values``
+
+****************************************************************************
+
NFD version 0.2.0 (changes since version 0.1.0)
-----------------------------------------------
@@ -21,109 +274,82 @@
- **Core**
- + Add support for temporary privilege drop and elevation (`Issue #1370
- <http://redmine.named-data.net/issues/1370>`_)
+ + Add support for temporary privilege drop and elevation (:issue:`1370`)
+ Add support to reinitialize multicast Faces and (partially) reload config file
- (`Issue #1584 <http://redmine.named-data.net/issues/1584>`_)
+ (:issue:`1584`)
- + Randomization routines are now uniform across all NFD modules
- (`Issue #1369 <http://redmine.named-data.net/issues/1369>`_)
+ + Randomization routines are now uniform across all NFD modules (:issue:`1369`)
- + Enable use of new NDN naming conventions
- (`Issue #1837 <http://redmine.named-data.net/issues/1837>`_ and
- `#1838 <http://redmine.named-data.net/issues/1838>`_)
+ + Enable use of new NDN naming conventions (:issue:`1837` and :issue:`1838`)
- **Faces**
- + `WebSocket <http://tools.ietf.org/html/rfc6455>`_ Face support
- (`Issue #1468 <http://redmine.named-data.net/issues/1468>`_)
+ + `WebSocket <http://tools.ietf.org/html/rfc6455>`_ Face support (:issue:`1468`)
- + Fix Ethernet Face support on Linux with ``libpcap`` version >=1.5.0
- (`Issue #1511 <http://redmine.named-data.net/issues/1511>`_)
+ + Fix Ethernet Face support on Linux with ``libpcap`` version >=1.5.0 (:issue:`1511`)
- + Fix to recognize IPv4-mapped IPv6 addresses in ``FaceUri``
- (`Issue #1635 <http://redmine.named-data.net/issues/1635>`_)
+ + Fix to recognize IPv4-mapped IPv6 addresses in ``FaceUri`` (:issue:`1635`)
- + Fix to avoid multiple onFail events
- (`Issue #1497 <http://redmine.named-data.net/issues/1497>`_)
+ + Fix to avoid multiple onFail events (:issue:`1497`)
- + Fix broken support of multicast UDP Faces on OSX
- (`Issue #1668 <http://redmine.named-data.net/issues/1668>`_)
+ + Fix broken support of multicast UDP Faces on OSX (:issue:`1668`)
- + On Linux, path MTU discovery on unicast UDPv4 faces is now disabled
- (`Issue #1651 <http://redmine.named-data.net/issues/1651>`_)
+ + On Linux, path MTU discovery on unicast UDPv4 faces is now disabled (:issue:`1651`)
- + Added link layer byte counts in FaceCounters
- (`Issue #1729 <http://redmine.named-data.net/issues/1729>`_)
+ + Added link layer byte counts in FaceCounters (:issue:`1729`)
- + Face IDs 0-255 are now reserved for internal NFD use
- (`Issue #1620 <http://redmine.named-data.net/issues/1620>`_)
+ + Face IDs 0-255 are now reserved for internal NFD use (:issue:`1620`)
- + Serialized StreamFace::send(Interest|Data) operations using queue
- (`Issue #1777 <http://redmine.named-data.net/issues/1777>`_)
+ + Serialized StreamFace::send(Interest|Data) operations using queue (:issue:`1777`)
- **Forwarding**
- + Outgoing Interest pipeline now allows strategies to request a fresh ``Nonce``
- (e.g., when the strategy needs to re-express the Interest)
- (`Issue #1596 <http://redmine.named-data.net/issues/1596>`_)
+ + Outgoing Interest pipeline now allows strategies to request a fresh ``Nonce`` (e.g., when
+ the strategy needs to re-express the Interest) (:issue:`1596`)
+ Fix in the incoming Data pipeline to avoid sending packets to the incoming Face
- (`Issue #1556 <http://redmine.named-data.net/issues/1556>`_)
+ (:issue:`1556`)
- + New ``RttEstimator`` class that implements the Mean-Deviation RTT estimator to be used
- in forwarding strategies
+ + New ``RttEstimator`` class that implements the Mean-Deviation RTT estimator to be used in
+ forwarding strategies
- + Fix memory leak caused by not removing PIT entry when Interest matches CS
- (`Issue #1882 <http://redmine.named-data.net/issues/1882>`_)
+ + Fix memory leak caused by not removing PIT entry when Interest matches CS (:issue:`1882`)
- + Fix spurious assertion in NCC strategy
- (`Issue #1853 <http://redmine.named-data.net/issues/1853>`_)
+ + Fix spurious assertion in NCC strategy (:issue:`1853`)
- **Tables**
+ Fix in ContentStore to properly adjust internal structure when ``Cs::setLimit`` is called
- (`Issue #1646 <http://redmine.named-data.net/issues/1646>`_)
+ (:issue:`1646`)
- + New option in configuration file to set an upper bound on ContentStore size
- (`Issue #1623 <http://redmine.named-data.net/issues/1623>`_)
+ + New option in configuration file to set an upper bound on ContentStore size (:issue:`1623`)
- + Fix to prevent infinite lifetime of Measurement entries
- (`Issue #1665 <http://redmine.named-data.net/issues/1665>`_)
+ + Fix to prevent infinite lifetime of Measurement entries (:issue:`1665`)
- + Introducing capacity limit in PIT NonceList
- (`Issue #1770 <http://redmine.named-data.net/issues/1770>`_)
+ + Introducing capacity limit in PIT NonceList (:issue:`1770`)
- + Fix memory leak in NameTree
- (`Issue #1803 <http://redmine.named-data.net/issues/1803>`_)
+ + Fix memory leak in NameTree (:issue:`1803`)
- + Fix segfault during Fib::removeNextHopFromAllEntries
- (`Issue #1816 <http://redmine.named-data.net/issues/1816>`_)
+ + Fix segfault during Fib::removeNextHopFromAllEntries (:issue:`1816`)
- **Management**
- + RibManager now fully support ``CHILD_INHERIT`` and ``CAPTURE`` flags
- (`Issue #1325 <http://redmine.named-data.net/issues/1325>`_)
+ + RibManager now fully support ``CHILD_INHERIT`` and ``CAPTURE`` flags (:issue:`1325`)
- + Fix in ``FaceManager`` to respond with canonical form of Face URI for Face creation
- command (`Issue #1619 <http://redmine.named-data.net/issues/1619>`_)
+ + Fix in ``FaceManager`` to respond with canonical form of Face URI for Face creation command
+ (:issue:`1619`)
- + Fix to prevent creation of duplicate TCP/UDP Faces due to async calls
- (`Issue #1680 <http://redmine.named-data.net/issues/1680>`_)
+ + Fix to prevent creation of duplicate TCP/UDP Faces due to async calls (:issue:`1680`)
- + Fix to properly handle optional ExpirationPeriod in RibRegister command
- (`Issue #1772 <http://redmine.named-data.net/issues/1772>`_)
+ + Fix to properly handle optional ExpirationPeriod in RibRegister command (:issue:`1772`)
- + Added functionality of publishing RIB status (RIB dataset) by RibManager
- (`Issue #1662 <http://redmine.named-data.net/issues/1662>`_)
+ + Added functionality of publishing RIB status (RIB dataset) by RibManager (:issue:`1662`)
- + Fix issue of not properly canceling route expiration during processing of
- ``unregister`` command
- (`Issue #1902 <http://redmine.named-data.net/issues/1902>`_)
+ + Fix issue of not properly canceling route expiration during processing of ``unregister``
+ command (:issue:`1902`)
- + Enable periodic clean up of route entries that refer to non-existing faces
- (`Issue #1875 <http://redmine.named-data.net/issues/1875>`_)
+ + Enable periodic clean up of route entries that refer to non-existing faces (:issue:`1875`)
- **Tools**
@@ -140,10 +366,9 @@
* HTTP server now presents status as XSL-formatted XML page
* XML dataset and formatted page now include certificate name of the corresponding NFD
- (`Issue #1807 <http://redmine.named-data.net/issues/1807>`_)
+ (:issue:`1807`)
- + Several fixes in ``ndn-autoconfig`` tool
- (`Issue #1595 <http://redmine.named-data.net/issues/1595>`_)
+ + Several fixes in ``ndn-autoconfig`` tool (:issue:`1595`)
+ Extended options in ``nfdc``:
@@ -151,12 +376,10 @@
* ``-o`` to specify origin for registration and unregistration commands
+ Enable ``all-faces-prefix'' option in ``nfd-autoreg`` to register prefix for all face
- (on-demand and non-on-demand)
- (`Issue #1861 <http://redmine.named-data.net/issues/1861>`_)
+ (on-demand and non-on-demand) (:issue:`1861`)
- + Enable processing auto-registration in ``nfd-autoreg`` for faces that existed
- prior to start of the tool
- (`Issue #1863 <http://redmine.named-data.net/issues/1863>`_)
+ + Enable processing auto-registration in ``nfd-autoreg`` for faces that existed prior to
+ start of the tool (:issue:`1863`)
- **Build**
@@ -165,6 +388,8 @@
- `Other small fixes and extensions
<https://github.com/named-data/NFD/compare/NFD-0.1.0...master>`_
+****************************************************************************
+
NFD version 0.1.0
-----------------
diff --git a/docs/conf.py b/docs/conf.py
index c261a1d..2ad1376 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -18,7 +18,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 ------------------------------------------------
@@ -30,6 +30,7 @@
# ones.
extensions = [
'sphinx.ext.todo',
+ 'redmine_issue',
]
def addExtensionIfExists(extension):
@@ -266,3 +267,5 @@
if os.getenv('GOOGLE_ANALYTICS', None):
googleanalytics_id = os.environ['GOOGLE_ANALYTICS']
googleanalytics_enabled = True
+
+redmine_project_url = "http://redmine.named-data.net/"
diff --git a/docs/doxygen.conf.in b/docs/doxygen.conf.in
index cc58aa6..2760b9b 100644
--- a/docs/doxygen.conf.in
+++ b/docs/doxygen.conf.in
@@ -1931,7 +1931,10 @@
PREDEFINED = NFD_LOG_INIT(x)= \
NFD_LOG_INCLASS_TEMPLATE_SPECIALIZATION_DEFINE(x,y)= \
NFD_LOG_INCLASS_2TEMPLATE_SPECIALIZATION_DEFINE(x,y,z)= \
- BOOST_STATIC_ASSERT(x)=
+ BOOST_STATIC_ASSERT(x)= \
+ BOOST_CONCEPT_ASSERT \
+ BOOST_CONCEPT_REQUIRES \
+ DECL_OVERRIDE=override
# 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/manpages.rst b/docs/manpages.rst
index 6a52897..4d8ee12 100644
--- a/docs/manpages.rst
+++ b/docs/manpages.rst
@@ -12,6 +12,7 @@
manpages/nfd-status-http-server
manpages/ndn-autoconfig
manpages/ndn-autoconfig-server
+ misc/local-prefix-discovery
manpages/nfd-autoreg
manpages/ndn-tlv-peek
manpages/ndn-tlv-poke
diff --git a/docs/misc/local-prefix-discovery.rst b/docs/misc/local-prefix-discovery.rst
index f1bca84..1916376 100644
--- a/docs/misc/local-prefix-discovery.rst
+++ b/docs/misc/local-prefix-discovery.rst
@@ -24,9 +24,9 @@
ResponseContent ::= Name+
.. note::
-ResponseContent should contain at least one Name, which should be routable
-towards the face from which the request has been received. The requester may
-process list of the returned names and pick whichever it wants to use.
+ ResponseContent should contain at least one Name, which should be routable
+ towards the face from which the request has been received. The requester may
+ process list of the returned names and pick whichever it wants to use.
For now, the ``/localhop/ndn-autoconf/routable-prefixes`` data is served by
:ref:`ndn-autoconfig-server`.
diff --git a/docs/redmine_issue.py b/docs/redmine_issue.py
new file mode 100644
index 0000000..35c3b12
--- /dev/null
+++ b/docs/redmine_issue.py
@@ -0,0 +1,70 @@
+# -*- 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, err:
+ raise ValueError('redmine_project_url configuration value is not set (%s)' % str(err))
+ #
+ 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