From 4a9582898fdcef9ff514802a09a74b521be2276f Mon Sep 17 00:00:00 2001
From: Anastasios Bithas <anastasiostam@gmail.com>
Date: Mon, 31 Jan 2022 15:12:40 +0000
Subject: [PATCH] Bug 1650197 - Add an extension to autolink bug xxxxxxx
 strings in docs to bugzilla hyperlinks r=sylvestre DONTBUILD

An extension is created that uses SphinxTransform to convert bug xxxxxxx strings that exist in docs to reference links that redirect to the appropriate bug in bugzilla

Differential Revision: https://phabricator.services.mozilla.com/D137385
---
 docs/_addons/bzlink.py | 62 ++++++++++++++++++++++++++++++++++++++++++
 docs/conf.py           |  2 ++
 2 files changed, 64 insertions(+)
 create mode 100644 docs/_addons/bzlink.py

diff --git a/docs/_addons/bzlink.py b/docs/_addons/bzlink.py
new file mode 100644
index 000000000000..8572794c7dfa
--- /dev/null
+++ b/docs/_addons/bzlink.py
@@ -0,0 +1,62 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from sphinx.transforms import SphinxTransform
+from docutils.nodes import reference, Text, paragraph
+import re
+
+
+class ConvertBugsToLinks(SphinxTransform):
+    # Convert text entries in paragraphs that are in the style of "bug xxxxx"
+    # to a hyperlink that leads to the appropriate bugzilla bug link.
+
+    default_priority = 400
+    bz_url = "https://bugzilla.mozilla.org/show_bug.cgi?id={0}"
+    bz_reg = r"bug[' '][0-9]\d*"
+
+    def apply(self):
+        def check_if_paragraph(o):
+            return isinstance(o, paragraph)
+
+        def check_if_text(o):
+            return (
+                not isinstance(o.parent, reference)
+                and isinstance(o, Text)
+                and re.search(self.bz_reg, o, re.IGNORECASE)
+            )
+
+        changed = True
+        while changed:
+            changed = self.textToReferences(check_if_paragraph, check_if_text)
+        return
+
+    def textToReferences(self, check_if_paragraph, check_if_text):
+        # Analyses the document and replaces from the paragraph nodes
+        # the Text element(s) that contain bz_reg matching strings.
+        # Whevever the matching strings are more than one and
+        # a correction is made, the function returns True.
+
+        for node in self.document.traverse(check_if_paragraph):
+            for text in node.traverse(check_if_text):
+                bugs = re.findall(self.bz_reg, text, re.IGNORECASE)
+                if len(bugs) == 0:
+                    continue
+                bug = bugs[0]
+                txtparts = text.split(bug, 1)
+                new_ref = reference(
+                    bug,
+                    bug,
+                    refuri=self.bz_url.format(bug.split()[1]),
+                )
+                txt_0 = Text(txtparts[0])
+                txt_1 = Text(txtparts[1])
+                text.parent.replace(text, [txt_0, new_ref, txt_1])
+                if len(bugs) > 1:
+                    return True
+        return False
+
+
+def setup(app):
+    app.add_transform(ConvertBugsToLinks)
+    return
diff --git a/docs/conf.py b/docs/conf.py
index 21b48f931be8..020f50911a54 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -25,6 +25,7 @@ EXTRA_PATHS = (
     "testing/mozbase/mozprocess",
     "third_party/python/jsmin",
     "third_party/python/which",
+    "docs/_addons",
 )
 
 sys.path[:0] = [os.path.join(topsrcdir, p) for p in EXTRA_PATHS]
@@ -45,6 +46,7 @@ extensions = [
     "sphinx_copybutton",
     "sphinx_markdown_tables",
     "sphinx_panels",
+    "bzlink",
 ]
 
 # JSDoc must run successfully for dirs specified, so running