[tor-commits] [stem/master] Adding a :spec: role

atagar at torproject.org atagar at torproject.org
Wed Apr 17 16:27:34 UTC 2013


commit 3ba0e6571bd0593c547bf27dd702679e12f802ef
Author: Damian Johnson <atagar at torproject.org>
Date:   Wed Apr 17 09:26:32 2013 -0700

    Adding a :spec: role
    
    Generalising our roles to also support a :spec: alias for torspec commits.
---
 docs/change_log.rst |    4 ++-
 docs/conf.py        |    3 +-
 docs/roles.py       |   99 +++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/trac.py        |   72 -------------------------------------
 4 files changed, 104 insertions(+), 74 deletions(-)

diff --git a/docs/change_log.rst b/docs/change_log.rst
index ff5dd21..d9fe02e 100644
--- a/docs/change_log.rst
+++ b/docs/change_log.rst
@@ -40,7 +40,8 @@ The following are only available within stem's `git repository
 
  * **Controller**
 
-  * :class:`~stem.response.events.AddrMapEvent` support for the new CACHED argument (:trac:`8596`, `spec <https://gitweb.torproject.org/torspec.git/commitdiff/25b0d43>`_)
+  * :class:`~stem.response.events.AddrMapEvent` support for the new CACHED argument (:trac:`8596`, :spec:`25b0d43`)
+  * :func:`~stem.control.Controller.attach_stream` could encounter an undocumented 555 response (:trac:`8701`, :spec:`7286576`)
 
  * **Website**
 
@@ -48,6 +49,7 @@ The following are only available within stem's `git repository
     improvements, most notably the addition of PyPI, FreeBSD, and RedHat.
   * Replaced default sphinx header with a navbar menu.
   * Added this change log.
+  * Added the `FAQ page <faq.html>`_.
   * Settled on a `logo
     <http://www.wpclipart.com/plants/assorted/P/plant_stem.png.html>`_ for
     stem.
diff --git a/docs/conf.py b/docs/conf.py
index 074fd89..801ef91 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -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', 'trac']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'roles']
 
 autodoc_member_order = 'bysource'
 autodoc_default_flags = ['members', 'show-inheritance', 'undoc-members']
@@ -230,3 +230,4 @@ man_pages = [
 ]
 
 trac_url = 'https://trac.torproject.org'
+spec_url = 'https://gitweb.torproject.org/torspec.git/commitdiff'
diff --git a/docs/roles.py b/docs/roles.py
new file mode 100644
index 0000000..0130ea3
--- /dev/null
+++ b/docs/roles.py
@@ -0,0 +1,99 @@
+import re
+
+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=[]):
+  """
+  Aliases :trac:`1234` to 'https://trac.torproject.org/1234'.
+
+  :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
+  link_text = 'ticket %s' % unescape(str(ticket_num))
+
+  return (
+    [make_link_node(rawtext, app, 'trac_url', link_text, str(ticket_num), options)],
+    [],
+  )
+
+
+def role_spec(name, rawtext, text, lineno, inliner, options={}, content=[]):
+  """
+  Aliases :spec:`25b0d43` to 'https://gitweb.torproject.org/torspec.git/commitdiff/25b0d43'.
+  """
+
+  # checking if the input is a valid short commit id
+
+  if not re.match('^[0-9a-f]{7}$', text):
+    msg = inliner.reporter.error(
+         'Spec tag expects a short commit id (seven hex characters): %s' % text, line=lineno)
+    prb = inliner.problematic(rawtext, rawtext, msg)
+
+    return ([prb], [msg])
+
+  app = inliner.document.settings.env.app
+
+  return (
+    [make_link_node(rawtext, app, 'spec_url', 'spec', text, options)],
+    [],
+  )
+
+
+def make_link_node(rawtext, app, url_type, link_text, slug, options):
+  """
+  Creates a link to a trac ticket.
+
+  :param rawtext: text being replaced with link node
+  :param app: sphinx application context
+  :param url_type: base for our url
+  :param link_text: text for the link
+  :param slug: ID of the thing to link to
+  :param options: options dictionary passed to role func
+  """
+
+  base_url = getattr(app.config, url_type, None)
+
+  if not base_url:
+    raise ValueError("'%s' isn't set in our config" % url_type)
+
+  ref = base_url.rstrip('/') + '/' + slug
+  set_classes(options)
+
+  return reference(rawtext, link_text, refuri = ref, **options)
+
+
+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')
+
+  app.add_role('spec', role_spec)
+  app.add_config_value('spec_url', None, 'env')
diff --git a/docs/trac.py b/docs/trac.py
deleted file mode 100644
index 7af5440..0000000
--- a/docs/trac.py
+++ /dev/null
@@ -1,72 +0,0 @@
-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
-
-  return (
-    [make_link_node(rawtext, app, 'ticket', str(ticket_num), options)],
-    [],
-  )
-
-
-def make_link_node(rawtext, app, link_type, slug, options):
-  """
-  Creates a link to a trac ticket.
-
-  :param rawtext: text being replaced with link node
-  :param app: sphinx application context
-  :param link_type: link type (issue, changeset, etc.)
-  :param slug: ID of the thing to link to
-  :param options: options dictionary passed to role func
-  """
-
-  trac_base_url = getattr(app.config, 'trac_url', None)
-
-  if not trac_base_url:
-    raise ValueError('trac_url is not set')
-
-  ref = trac_base_url.rstrip('/') + '/' + slug
-  set_classes(options)
-  name = link_type + ' ' + unescape(slug)  # sets the text to 'ticket 345'
-
-  return reference(rawtext, name, refuri = ref, **options)
-
-
-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')



More information about the tor-commits mailing list