docs: Add a extension that allows links to reference current release.

docs/conf.py

@@ -18,7 +18,7 @@ sys.path.insert(0, os.path.abspath('.'))
 
 # 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.autodoc', 'ext_argparse', 'ext_github']
+extensions = ['sphinx.ext.autodoc', 'ext_argparse', 'ext_github', 'ext_releaseref']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/ext_releaseref.py

@@ -0,0 +1,27 @@
+"""Creates links that allows substituting the current release
+within the title or target."""
+
+import os.path
+
+from docutils import nodes
+from sphinx.util.nodes import split_explicit_title
+
+
+def releaseref_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    config = inliner.document.settings.env.config
+    text = text.replace("|version|", config.version)
+    text = text.replace("|release|", config.release)
+
+    has_explicit_title, title, target = split_explicit_title(text)
+    if not has_explicit_title:
+        title = os.path.basename(target)
+
+    node = nodes.reference(rawtext, title, refuri=target, **options)
+
+    return [node], []
+
+
+def setup(app):
+    app.add_role("releaseref", releaseref_role)
+
+