[tor-commits] [bridgedb/develop] Add Sphinx extension for referencing Tor Trac tickets.

[isis at torproject.org]

commit 8df13d2b5f2bcc4a19c32017bcdf81efe0f6401d
Author: Isis Lovecruft <isis at torproject.org>
Date:   Thu Jun 18 04:38:19 2015 +0000

    Add Sphinx extension for referencing Tor Trac tickets.
---
 doc/sphinx/ext/traclinks.py       |   37 +++++++++++++++++++++++++++++++++++++
 doc/sphinx/source/conf.py         |    3 ++-
 lib/bridgedb/parse/descriptors.py |    8 ++++----
 3 files changed, 43 insertions(+), 5 deletions(-)

diff --git a/doc/sphinx/ext/traclinks.py b/doc/sphinx/ext/traclinks.py
new file mode 100644
index 0000000..fd2d9b3
--- /dev/null
+++ b/doc/sphinx/ext/traclinks.py
@@ -0,0 +1,37 @@
+"""Sphinx/docutils extension to create links to a Trac site using a
+RestructuredText interpreted text role that looks like this::
+
+    :trac:`trac_link_text`
+
+for example::
+
+    :trac:`#2015`
+
+creates a link to ticket number 2015.
+
+adapted from recipe here_.
+
+.. _here: http://stackoverflow.com/a/2111327/13564
+"""
+
+import urllib
+from docutils import nodes, utils
+
+def make_trac_link(name, rawtext, text, lineno, inliner,
+                   options={}, content=[]):
+    env = inliner.document.settings.env
+    trac_url =  env.config.traclinks_base_url
+    ref = trac_url + urllib.quote(text, safe='')
+    node = nodes.reference(rawtext,
+                           utils.unescape(text),
+                           refuri=ref,
+                           **options)
+    return [node],[]
+
+
+def setup(app):
+    """setup function to register the extension"""
+    app.add_config_value('traclinks_base_url',
+                         'https://bugs.torproject.org/',
+                         'env')
+    app.add_role('trac', make_trac_link)
diff --git a/doc/sphinx/source/conf.py b/doc/sphinx/source/conf.py
index 5cd485f..e733c42 100644
--- a/doc/sphinx/source/conf.py
+++ b/doc/sphinx/source/conf.py
@@ -116,7 +116,8 @@ extensions = ['sphinx.ext.autodoc',
               'sphinxarg.ext',
               'sphinxcontrib.fulltoc',
               'repoze.sphinx.autointerface',
-              'apilinks_sphinxext']
+              'apilinks_sphinxext',
+              'traclinks']
 
 todo_include_todos = True
 
diff --git a/lib/bridgedb/parse/descriptors.py b/lib/bridgedb/parse/descriptors.py
index 46f959e..81cba7f 100644
--- a/lib/bridgedb/parse/descriptors.py
+++ b/lib/bridgedb/parse/descriptors.py
@@ -69,10 +69,10 @@ def parseNetworkStatusFile(filename, validate=True, skipAnnotations=True,
                            descriptorClass=RouterStatusEntryV3):
     """Parse a file which contains an ``@type bridge-networkstatus`` document.
 
-    See `ticket #12254 <https://bugs.torproject.org/12254>`__ for why
-    networkstatus-bridges documents don't look anything like the networkstatus
-    v2 documents that they are purported to look like. They are missing all
-    headers, and the entire footer including authority signatures.
+    See :trac:`#12254` for why networkstatus-bridges documents don't look
+    anything like the networkstatus v2 documents that they are purported to
+    look like. They are missing all headers, and the entire footer including
+    authority signatures.
 
     :param str filename: The location of the file containing bridge
         networkstatus descriptors.