Backport source role for linking to files in the cpython repo.

Georg added this role in our 3.2 doc tools and gave the greenlight for a
backport on python-dev.

This code is a simplified version of the 3.2 code; the version of Sphinx
used with Python 2.7 doesn’t have the function used to parse markup like
:role:`text to be displayed <text to be processed>` (I was persuaded it
was a standard reST construct, but it is actually a Sphinx innovation
that has to be supported explicitly in role code —I’ll be damned).  It
is thus not possible to write for example :source:`the NEWS file
<Misc/NEWS>`, but :source:`Misc/NEWS` will work.
This commit is contained in:
Éric Araujo 2011-08-19 00:12:33 +02:00
parent 569ff91a5a
commit f595a76d3d
1 changed files with 11 additions and 1 deletions

View File

@ -5,11 +5,12 @@
Sphinx extension with Python doc-specific markup.
:copyright: 2008, 2009 by Georg Brandl.
:copyright: 2008-2011 by Georg Brandl.
:license: Python license.
"""
ISSUE_URI = 'http://bugs.python.org/issue%s'
SOURCE_URI = 'http://hg.python.org/cpython/file/2.7/%s'
from docutils import nodes, utils
@ -44,6 +45,14 @@ def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
return [refnode], []
# Support for linking to Python source files easily
def source_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
path = utils.unescape(text)
refnode = nodes.reference(path, path, refuri=SOURCE_URI % path)
return [refnode], []
# Support for marking up implementation details
from sphinx.util.compat import Directive
@ -168,6 +177,7 @@ def parse_opcode_signature(env, sig, signode):
def setup(app):
app.add_role('issue', issue_role)
app.add_role('source', source_role)
app.add_directive('impl-detail', ImplementationDetail)
app.add_builder(PydocTopicsBuilder)
app.add_builder(suspicious.CheckSuspiciousMarkupBuilder)