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.

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 @@ 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)