commit 3ba0e6571bd0593c547bf27dd702679e12f802ef Author: Damian Johnson <atagar@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')