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.
diff --git a/Doc/tools/sphinxext/pyspecific.py b/Doc/tools/sphinxext/pyspecific.py
index 415310d..a588b4d 100644
--- a/Doc/tools/sphinxext/pyspecific.py
+++ b/Doc/tools/sphinxext/pyspecific.py
@@ -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 @@
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 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)