From f6f0d97358b83c06007f329f6692d52ab985f9c9 Mon Sep 17 00:00:00 2001
From: Shengyu Zhang <i@silverrainz.me>
Date: Sun, 24 Mar 2024 14:18:18 +0800
Subject: [PATCH 1/2] Add literal formatting for extlinks and get rid of custom
 extension

See also
https://github.com/sphinx-doc/sphinx/issues/11745#issuecomment-1888465545
---
 _extensions/custom_roles.py | 43 -------------------------------------
 conf.py                     | 18 ++++++++++------
 requirements.txt            |  1 +
 3 files changed, 13 insertions(+), 49 deletions(-)
 delete mode 100644 _extensions/custom_roles.py

diff --git a/_extensions/custom_roles.py b/_extensions/custom_roles.py
deleted file mode 100644
index f8c9bb895..000000000
--- a/_extensions/custom_roles.py
+++ /dev/null
@@ -1,43 +0,0 @@
-"""Sphinx extension to add custom roles.
-
-Based on https://protips.readthedocs.io/link-roles.html
-"""
-import urllib.parse
-
-from docutils import nodes
-
-
-def setup(app):
-    # role to link to cpython files
-    app.add_role(
-        "cpy-file",
-        autolink("https://github.com/python/cpython/blob/main/{}"),
-    )
-    # role to link to cpython labels
-    app.add_role(
-        "gh-label",
-        autolink("https://github.com/python/cpython/labels/{}"),
-    )
-    # Parallel safety:
-    # https://www.sphinx-doc.org/en/master/extdev/index.html#extension-metadata
-    return {"parallel_read_safe": True, "parallel_write_safe": True}
-
-
-def autolink(pattern):
-    def role(name, rawtext, text, lineno, inliner, _options=None, _content=None):
-        """Combine literal + reference (unless the text is prefixed by a !)."""
-        if " " in text:
-            url_text = urllib.parse.quote(text)
-        else:
-            url_text = text
-        url = pattern.format(url_text)
-        # don't create a reference if the text starts with !
-        if text.startswith('!'):
-            node = nodes.literal(rawtext, text[1:])
-        else:
-            node = nodes.reference(
-                rawtext, '', nodes.literal(rawtext, text), refuri=url, internal=False
-            )
-        return [node], []
-
-    return role
diff --git a/conf.py b/conf.py
index 825cfb5b5..2bec2b6e9 100644
--- a/conf.py
+++ b/conf.py
@@ -1,12 +1,6 @@
-import os
-import sys
 import time
 
-# Location of custom extensions.
-sys.path.insert(0, os.path.abspath(".") + "/_extensions")
-
 extensions = [
-    'custom_roles',
     'notfound.extension',
     'sphinx.ext.extlinks',
     'sphinx.ext.intersphinx',
@@ -15,6 +9,7 @@
     'sphinx_inline_tabs',
     'sphinxext.opengraph',
     'sphinxext.rediraffe',
+    'sphinxnotes.comboroles',
 ]
 
 # The master toctree document.
@@ -178,6 +173,10 @@
 # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
 extlinks = {
     "github": ("https://github.com/%s/", "%s"),
+
+    # Not used directly in document, see sphinxnotes-comborole config.
+    "_cpy-file": ("https://github.com/python/cpython/blob/main/%s", "%s"),
+    "_gh-label": ("https://github.com/python/cpython/labels/%s", "%s"),
 }
 
 # sphinxext-opengraph config
@@ -195,3 +194,10 @@
 copybutton_prompt_text = "$ "
 # https://sphinx-copybutton.readthedocs.io/en/latest/use.html#honor-line-continuation-characters-when-copying-multline-snippets
 copybutton_line_continuation_character = "\\"
+
+# sphinxnotes-comboroles config.
+comboroles_roles = {
+    # Add literal formatting for extlink roles.
+    "cpy-file": ["literal", "_cpy-file"],
+    "gh-label": ["literal", "_gh-label"],
+}
diff --git a/requirements.txt b/requirements.txt
index 219122e4c..c14c91773 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -8,3 +8,4 @@ sphinx_copybutton>=0.3.3
 sphinxext-opengraph>=0.7.1
 sphinxext-rediraffe
 Sphinx~=7.2.6
+sphinxnotes-comboroles>=1.0

From d070ecd013b139ada0246761fe267dca0f4bb71f Mon Sep 17 00:00:00 2001
From: Shengyu Zhang <i@silverrainz.me>
Date: Sun, 24 Mar 2024 17:47:48 +0800
Subject: [PATCH 2/2] Fix lint error

---
 conf.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/conf.py b/conf.py
index 2bec2b6e9..e60cdcd6a 100644
--- a/conf.py
+++ b/conf.py
@@ -173,7 +173,6 @@
 # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
 extlinks = {
     "github": ("https://github.com/%s/", "%s"),
-
     # Not used directly in document, see sphinxnotes-comborole config.
     "_cpy-file": ("https://github.com/python/cpython/blob/main/%s", "%s"),
     "_gh-label": ("https://github.com/python/cpython/labels/%s", "%s"),