[tor-commits] [stem/master] Implemented custom sphinx role :trac: for trac tickets

[atagar at torproject.org]

commit 0567974e7c3e0610dfa62e54b0a96ef54fd59866
Author: Tomasz Kunikowski <tomasz.kunikowski at gmail.com>
Date:   Sun Apr 14 22:29:06 2013 +0200

    Implemented custom sphinx role :trac: for trac tickets
    
    Modified:
    	docs/conf.py
    
    Added:
    	docs/trac.py
    
    In accodrance to ticket #8671
    Using :trac:`1234` will display 'ticket #1234'
---
 docs/conf.py |    6 +++-
 docs/trac.py |   71 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 75 insertions(+), 2 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 0bce09f..7723736 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -18,7 +18,7 @@ import sys, os
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 
 sys.path.insert(0, os.path.abspath('..'))
-
+sys.path.append(os.path.abspath('.'))
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -26,7 +26,7 @@ needs_sphinx = '1.1' # required for the sphinx-apidoc command
 
 # 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.autodoc', 'sphinx.ext.viewcode']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'trac']
 
 autodoc_member_order = 'bysource'
 autodoc_default_flags = ['members', 'show-inheritance', 'undoc-members']
@@ -223,3 +223,5 @@ man_pages = [
     ('index', 'stem', u'Stem Documentation',
      ['%s (%s)' % (__author__, __contact__)], 1)
 ]
+
+trac_url = 'https://trac.torproject.org/projects/tor'
diff --git a/docs/trac.py b/docs/trac.py
new file mode 100644
index 0000000..afc74e8
--- /dev/null
+++ b/docs/trac.py
@@ -0,0 +1,71 @@
+from docutils.utils import unescape
+from docutils.nodes import reference
+from docutils.parsers.rst.roles import set_classes
+
+
+def role_trac(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    """Returns two part tuple consisting of node and system messages.
+    Both 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.
+    """
+
+    # checking if the number is valid
+    try:
+        ticket_num = int(text)
+        if ticket_num <= 0:
+            raise ValueError
+
+    except ValueError:
+        msg = inliner.reporter.error(
+            'Invalid trac ticket: %s' % (text), line=lineno)
+        prb = inliner.problematic(rawtext, rawtext, msg)
+        return ([prb], [msg])
+
+    app = inliner.document.settings.env.app
+    node = make_link_node(rawtext, app, 'ticket', str(ticket_num), options)
+    return ([node], [])
+
+
+def make_link_node(rawtext, app, type, slug, options):
+    """Creates a link to a trac ticket.
+
+    :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.
+    """
+
+    # checking if trac_url is set in conf.py
+    try:
+        base = app.config.trac_url
+        if not base:
+            raise AttributeError
+
+    except AttributeError, e:
+        raise ValueError('trac_url is not set (%s)' % str(e))
+
+    slash = '/' if base[-1] != '/' else ''
+    ref = base + slash + type + '/' + slug
+    set_classes(options)
+    name = type + ' #' + unescape(slug)
+    node = reference(rawtext, name, refuri=ref, **options)
+    return node
+
+
+def setup(app):
+    """Installs the plugin.
+
+    :param app: Sphinx application context.
+    """
+
+    app.add_role('trac', role_trac)
+    app.add_config_value('trac_url', None, 'env')
+    return