Added :issue: role to link github issues

Author: spectras

docs/_ext/github.py

@@ -0,0 +1,31 @@
+# Sphinx helper for github issue references
+from docutils import nodes
+from docutils.parsers.rst.roles import set_classes
+
+ISSUE_URL = 'https://github.com/{owner}/{repo}/issues/{num}'
+
+def github_issue_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
+    try:
+        issuenum = int(text)
+        if issuenum <= 0:
+            raise ValueError()
+    except ValueError:
+        msg = inliner.reporter.error(
+            'Issuse number must be a strictly positive integer. Number "%s" '
+            'is invalid.' % text, line=lineno)
+        prb = inliner.problematic(rawtext, rawtext, msg)
+        return [prb], [msg]
+
+    ref = ISSUE_URL.format(
+        owner = inliner.document.settings.env.config['github_owner'],
+        repo = inliner.document.settings.env.config['github_repo'],
+        num = issuenum,
+    )
+    set_classes(options)
+    node = nodes.reference(rawtext, '#%d' % issuenum, refuri=ref, **options)
+    return [node], []
+
+def setup(app):
+    app.add_config_value('github_owner', None, 'html')
+    app.add_config_value('github_repo', None, 'html')
+    app.add_role('issue', github_issue_role)

docs/conf.py

@@ -16,7 +16,10 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+
+sys.path.extend((
+    os.path.abspath(os.path.join(os.path.dirname(__file__), '_ext')),
+))
 
 # -- General configuration -----------------------------------------------------
 
@@ -25,7 +28,7 @@
 
 # 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.intersphinx']
+extensions = ['sphinx.ext.intersphinx', 'github']
 intersphinx_mapping = {
     'python': ('http://docs.python.org/2.6', None),
     'django': ('http://readthedocs.org/docs/django/en/latest/', None),
@@ -218,3 +221,9 @@
     ('index', 'project', u'Django Hvad Documentation',
      [u'Kristian Øllegaard, Jonas Obrist & contributors'], 1)
 ]
+
+# -- Options for local extensions ----------------------------------------------
+
+github_owner = 'KristianOellegaard'
+github_repo = 'django-hvad'
+