[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