Add a Sphinx role for linking GitLab issues/MRs

Define a :gl: Sphinx role that takes a GitLab issue/MR number as an
argument and creates a hyperlink to the relevant ISC GitLab URL.  This
makes it easy to reach ISC GitLab pages directly from the release notes.

Make all GitLab references in the release notes use the new Sphinx role.

doc/arm/conf.py

@@ -11,6 +11,62 @@
 
 # flake8: noqa: E501
 
+from typing import List, Tuple
+
+from docutils import nodes
+from docutils.nodes import Node, system_message
+from docutils.parsers.rst import roles
+
+from sphinx import addnodes
+from sphinx.util.docutils import ReferenceRole
+
+
+GITLAB_BASE_URL = 'https://gitlab.isc.org/isc-projects/bind9/-/'
+
+
+# Custom Sphinx role enabling automatic hyperlinking to GitLab issues/MRs.
+class GitLabRefRole(ReferenceRole):
+    def __init__(self, base_url: str) -> None:
+        self.base_url = base_url
+        super().__init__()
+
+    def run(self) -> Tuple[List[Node], List[system_message]]:
+        gl_identifier = '[GL %s]' % self.target
+
+        target_id = 'index-%s' % self.env.new_serialno('index')
+        entries = [('single', 'GitLab; ' + gl_identifier, target_id, '', None)]
+
+        index = addnodes.index(entries=entries)
+        target = nodes.target('', '', ids=[target_id])
+        self.inliner.document.note_explicit_target(target)
+
+        try:
+            refuri = self.build_uri()
+            reference = nodes.reference('', '', internal=False, refuri=refuri,
+                                        classes=['gl'])
+            if self.has_explicit_title:
+                reference += nodes.strong(self.title, self.title)
+            else:
+                reference += nodes.strong(gl_identifier, gl_identifier)
+        except ValueError:
+            error_text = 'invalid GitLab identifier %s' % self.target
+            msg = self.inliner.reporter.error(error_text, line=self.lineno)
+            prb = self.inliner.problematic(self.rawtext, self.rawtext, msg)
+            return [prb], [msg]
+
+        return [index, target, reference], []
+
+    def build_uri(self):
+        if self.target[0] == '#':
+            return self.base_url + 'issues/%d' % int(self.target[1:])
+        if self.target[0] == '!':
+            return self.base_url + 'merge_requests/%d' % int(self.target[1:])
+        raise ValueError
+
+
+def setup(_):
+    roles.register_local_role('gl', GitLabRefRole(GITLAB_BASE_URL))
+
 #
 # Configuration file for the Sphinx documentation builder.
 #