commit 0567974e7c3e0610dfa62e54b0a96ef54fd59866 Author: Tomasz Kunikowski tomasz.kunikowski@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