doc: Linkify issue numbers in changelog to GitHub

1 files changed, 24 insertions, 0 deletions

diff --git a/doc/conf.py b/doc/conf.py
index 3b39aa6d5..ccc2788f0 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -1,5 +1,6 @@
 # Sphinx documentation build configuration file
 
+import os
 import re
 
 import sphinx
@@ -139,10 +140,33 @@ def parse_event(env, sig, signode):
     return name
 
 
+def linkify_issues_in_changelog(app, docname, source):
+    """ Linkify issue references like #123 in changelog to GitHub. """
+
+    if docname == 'changes':
+        changelog_path = os.path.join(os.path.dirname(__file__), "../CHANGES")
+        # this path trickery is needed because this script can
+        # be invoked with different working directories:
+        # * running make in docs/
+        # * running python setup.py build_sphinx in the repo root dir
+
+        with open(changelog_path) as f:
+            changelog = f.read()
+
+        def linkify(match):
+            url = 'https://github.com/sphinx-doc/sphinx/issues/' + match[1]
+            return '`{} <{}>`_'.format(match[0], url)
+
+        linkified_changelog = re.sub(r'(?:PR)?#([0-9]+)\b', linkify, changelog)
+
+        source[0] = source[0].replace('.. include:: ../CHANGES', linkified_changelog)
+
+
 def setup(app):
     from sphinx.ext.autodoc import cut_lines
     from sphinx.util.docfields import GroupedField
     app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
+    app.connect('source-read', linkify_issues_in_changelog)
     app.add_object_type('confval', 'confval',
                         objname='configuration value',
                         indextemplate='pair: %s; configuration value')