docs/_addons/bzlink.py

   1 # This Source Code Form is subject to the terms of the Mozilla Public
   2 # License, v. 2.0. If a copy of the MPL was not distributed with this
   3 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
   4
   5 import re
   6
   7 from docutils.nodes import Text, paragraph, reference
   8 from sphinx.transforms import SphinxTransform
   9
  10
  11 class ConvertBugsToLinks(SphinxTransform):
  12     # Convert text entries in paragraphs that are in the style of "bug xxxxx"
  13     # to a hyperlink that leads to the appropriate bugzilla bug link.
  14
  15     default_priority = 400
  16     bz_url = "https://bugzilla.mozilla.org/show_bug.cgi?id={0}"
  17     bz_reg = r"bug[' '][0-9]\d*"
  18
  19     def apply(self):
  20         def check_if_paragraph(o):
  21             return isinstance(o, paragraph)
  22
  23         def check_if_text(o):
  24             return (
  25                 not isinstance(o.parent, reference)
  26                 and isinstance(o, Text)
  27                 and re.search(self.bz_reg, o, re.IGNORECASE)
  28             )
  29
  30         changed = True
  31         while changed:
  32             changed = self.textToReferences(check_if_paragraph, check_if_text)
  33         return
  34
  35     def textToReferences(self, check_if_paragraph, check_if_text):
  36         # Analyses the document and replaces from the paragraph nodes
  37         # the Text element(s) that contain bz_reg matching strings.
  38         # Whevever the matching strings are more than one and
  39         # a correction is made, the function returns True.
  40
  41         for node in self.document.traverse(check_if_paragraph):
  42             for text in node.traverse(check_if_text):
  43                 bugs = re.findall(self.bz_reg, text, re.IGNORECASE)
  44                 if len(bugs) == 0:
  45                     continue
  46                 bug = bugs[0]
  47                 txtparts = text.split(bug, 1)
  48                 new_ref = reference(
  49                     bug,
  50                     bug,
  51                     refuri=self.bz_url.format(bug.split()[1]),
  52                 )
  53                 txt_0 = Text(txtparts[0])
  54                 txt_1 = Text(txtparts[1])
  55                 text.parent.replace(text, [txt_0, new_ref, txt_1])
  56                 if len(bugs) > 1:
  57                     return True
  58         return False
  59
  60
  61 def setup(app):
  62     app.add_transform(ConvertBugsToLinks)
  63     return