From b8c73dd026fd667f31a81aad29cf0e37482e3f68 Mon Sep 17 00:00:00 2001
From: Remco de Boer <29308176+redeboer@users.noreply.github.com>
Date: Sat, 9 Dec 2023 17:25:02 +0100
Subject: [PATCH] FEAT: define `wiki` Sphinx role

Imported from here:

https://github.com/ComPWA/PWA-pages/blob/aa5486fc1ec6800efd1be52caf6961a1bfc9f5aa/docs/conf.py\#L322-L351
---
 .cspell.json                      |  1 +
 .vscode/settings.json             |  8 +-------
 src/sphinx_api_relink/__init__.py | 24 ++++++++++++++++++++++++
 3 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/.cspell.json b/.cspell.json
index a7118cd..2426931 100644
--- a/.cspell.json
+++ b/.cspell.json
@@ -45,6 +45,7 @@
     "refspecific",
     "reftarget",
     "reftype",
+    "refuri",
     "rtfd",
     "srcdir",
     "templatedir"
diff --git a/.vscode/settings.json b/.vscode/settings.json
index 3a09823..4c877ec 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -53,11 +53,5 @@
   "python.testing.unittestEnabled": false,
   "rewrap.wrappingColumn": 88,
   "ruff.enable": true,
-  "ruff.organizeImports": true,
-  "search.exclude": {
-    "**/tests/**/__init__.py": true,
-    "*/.pydocstyle": true,
-    "src/*/*/__init__.py": true,
-    "src/*/__init__.py": true
-  }
+  "ruff.organizeImports": true
 }
diff --git a/src/sphinx_api_relink/__init__.py b/src/sphinx_api_relink/__init__.py
index 5a1da5a..3b15356 100644
--- a/src/sphinx_api_relink/__init__.py
+++ b/src/sphinx_api_relink/__init__.py
@@ -13,8 +13,10 @@
 from sphinx_api_relink.linkcode import get_linkcode_resolve
 
 if TYPE_CHECKING:
+    from docutils.parsers.rst.states import Inliner
     from sphinx.application import Sphinx
     from sphinx.environment import BuildEnvironment
+    from sphinx.util.typing import RoleFunction
 
 
 def setup(app: Sphinx) -> dict[str, Any]:
@@ -29,6 +31,7 @@ def setup(app: Sphinx) -> dict[str, Any]:
     app.connect("config-inited", set_linkcode_resolve)
     app.connect("config-inited", generate_apidoc)
     app.connect("config-inited", replace_type_to_xref)
+    app.add_role("wiki", wiki_role("https://en.wikipedia.org/wiki/%s"))
     return {
         "parallel_read_safe": True,
         "parallel_write_safe": True,
@@ -187,3 +190,24 @@ def _create_nodes(env: BuildEnvironment, title: str) -> list[nodes.Node]:
             pending_xref_condition("", title, condition="*"),
         ]
     return [nodes.Text(short_name)]
+
+
+def wiki_role(pattern: str) -> RoleFunction:
+    def role(  # noqa: PLR0913
+        name: str,
+        rawtext: str,
+        text: str,
+        lineno: int,
+        inliner: Inliner,
+        options: dict | None = None,
+        content: list[str] | None = None,
+    ) -> tuple[list[nodes.Node], list[nodes.system_message]]:
+        output_text = text
+        output_text = output_text.replace("_", " ")
+        url = pattern % (text,)
+        if options is None:
+            options = {}
+        reference_node = nodes.reference(rawtext, output_text, refuri=url, **options)
+        return [reference_node], []
+
+    return role