deploy: 7dd793f

CNAME

@@ -0,0 +1 @@
+docs.openverse.org

_downloads/7c06dc7fa79c7a8feb2fbe872ad1e362/link_usernames.py

@@ -0,0 +1,119 @@
+"""GitHub Username Linking
+
+Based on: https://www.sphinx-doc.org/en/master/extdev/appapi.html#event-source-read
+and: https://stackoverflow.com/a/31924901/3277713  CC BY-SA 3.0 by C_Z_
+
+This extension replaces username references of the form `@username` with a link
+to the user's GitHub profile.
+
+The plugin ignores code inside of fixed text blocks, including code blocks and backticks.
+"""
+
+import re
+
+from docutils import nodes
+from sphinx.application import Sphinx
+from sphinx.transforms import SphinxTransform
+from sphinx.util import logging
+
+
+logger = logging.getLogger(__name__)
+
+# Format to use for the link to the GitHub profile
+GITHUB_USERNAME_TEMPLATE = "https://github.com/{username}"
+# Format to use for team mentions
+GITHUB_TEAM_TEMPLATE = "https://github.com/orgs/{org}/teams/{team}"
+
+# Regex to match username references
+GITHUB_USERNAME_REGEX = re.compile(
+    r"""
+@(?P<username>[A-Za-z0-9-]+)  # Match @ then any alphanumeric character or - for the username
+(?P<team>/[A-Za-z0-9-]+)?  # If this is a team reference, match the team separately
+""",
+    flags=re.VERBOSE,
+)
+
+
+class GitHubUserMentions(SphinxTransform):
+    default_priority = 999
+
+    def apply(self) -> None:
+        for node in self.document.findall(nodes.Text):
+            parent = node.parent
+
+            # ignore existing links, back ticks, and code blocks
+            ignore_types = (nodes.reference, nodes.literal, nodes.FixedTextElement)
+            if isinstance(parent, ignore_types):
+                continue
+
+            text = str(node)
+            new_nodes = []
+            prev_mention_node_ref = 0
+            for match in GITHUB_USERNAME_REGEX.finditer(text):
+                # The full match including the leading @
+                mention = match.group(0)
+
+                username = match.group("username")
+
+                # `team` will be None if not a team mention
+                # If it is a team mention, then `username` will be the org
+                team = match.group("team")
+
+                # extract the text between the last user mention and the
+                # current user mention and put it into a new text node
+                head = text[prev_mention_node_ref : match.start()]
+                if head:
+                    new_nodes.append(nodes.Text(head))
+
+                # adjust the position of the last user mention in the
+                # text
+                prev_mention_node_ref = match.end()
+
+                textnode = nodes.Text(mention)
+                refnode = nodes.reference()
+
+                if team:
+                    url = GITHUB_TEAM_TEMPLATE.format(
+                        org=username,
+                        team=team.lstrip("/"),
+                    )
+                    title = f"Team {username}{team} on GitHub"
+                else:
+                    url = GITHUB_USERNAME_TEMPLATE.format(
+                        username=username,
+                    )
+                    title = f"{username} on GitHub"
+
+                refnode["refuri"] = url
+                refnode["reftitle"] = title
+                refnode.append(textnode)
+
+                new_nodes.append(refnode)
+
+            if not new_nodes:
+                # no user mentions were found, move on to the next node
+                continue
+
+            # extract the remaining text after the last user mention, and
+            # put it into a text node
+            tail = text[prev_mention_node_ref:]
+            if tail:
+                new_nodes.append(nodes.Text(tail))
+            # find and remove the original node, and insert all new nodes
+            # instead
+            parent.replace(node, new_nodes)
+
+
+def init_transformer(app: Sphinx) -> None:
+    if app.config.githubusermention:
+        app.add_transform(GitHubUserMentions)
+
+
+def setup(app: Sphinx):
+    app.add_config_value("githubusermention", None, "env")
+    app.connect("builder-inited", init_transformer)
+    return {
+        "version": "1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }