From a807742a96ff2583e35d83b0b2301ed1a7eed02b Mon Sep 17 00:00:00 2001
From: Matt Wang <mattwang44@gmail.com>
Date: Thu, 10 Jul 2025 03:50:46 +0800
Subject: [PATCH] feat: add checker for detecting role with extra backtick

---
 sphinxlint/checkers.py                            | 13 +++++++++++++
 sphinxlint/rst.py                                 |  7 +++++++
 tests/fixtures/xfail/role-with-extra-backtick.rst | 15 +++++++++++++++
 3 files changed, 35 insertions(+)
 create mode 100644 tests/fixtures/xfail/role-with-extra-backtick.rst

diff --git a/sphinxlint/checkers.py b/sphinxlint/checkers.py
index 05afe352d..4f4dbe9fd 100644
--- a/sphinxlint/checkers.py
+++ b/sphinxlint/checkers.py
@@ -301,6 +301,19 @@ def check_role_with_double_backticks(file, lines, options=None):
             )
 
 
+@checker(".rst", ".po")
+def check_role_with_extra_backtick(filename, lines, options):
+    """Check for extra backtick in roles.
+
+    Bad:  :func:`foo``
+    Bad:  :func:``foo`
+    Good: :func:`foo`
+    """
+    for lno, line in enumerate(lines, start=1):
+        for match in rst.ROLE_WITH_EXTRA_BACKTICK_RE.finditer(line):
+            yield lno, f"Extra backtick in role: {match.group(0).strip()!r}"
+
+
 @checker(".rst", ".po")
 def check_missing_space_before_role(file, lines, options=None):
     """Search for missing spaces before roles.
diff --git a/sphinxlint/rst.py b/sphinxlint/rst.py
index 4c8c02617..5ca60c3ba 100644
--- a/sphinxlint/rst.py
+++ b/sphinxlint/rst.py
@@ -249,6 +249,13 @@ def inline_markup_gen(start_string, end_string, extra_allowed_before=""):
 # :const:`None`
 DOUBLE_BACKTICK_ROLE_RE = re.compile(rf"(?<!``){ROLE_HEAD}``")
 
+# Find roles with extra backtick like:
+# :mod:`!cgi`` (extra backtick at the end)
+# :mod:``!cgi` (extra backtick at the beginning)
+ROLE_WITH_EXTRA_BACKTICK_RE = re.compile(
+    rf"({ROLE_HEAD}(?:``[^`\s]+`(?!\S)|`[^`\s]+``))(?!`)"
+)
+
 START_STRING_PREFIX = f"(^|(?<=\\s|[{OPENERS}{DELIMITERS}|]))"
 END_STRING_SUFFIX = f"($|(?=\\s|[\x00{CLOSING_DELIMITERS}{DELIMITERS}{CLOSERS}|]))"
 
diff --git a/tests/fixtures/xfail/role-with-extra-backtick.rst b/tests/fixtures/xfail/role-with-extra-backtick.rst
new file mode 100644
index 000000000..a5082affa
--- /dev/null
+++ b/tests/fixtures/xfail/role-with-extra-backtick.rst
@@ -0,0 +1,15 @@
+.. expect: Extra backtick in role: ':mod:`!cgi``' (role-with-extra-backtick)
+.. expect: Extra backtick in role: ':mod:``!cgitb`' (role-with-extra-backtick)
+.. expect: Extra backtick in role: ':func:`foo``' (role-with-extra-backtick)
+.. expect: Extra backtick in role: ':class:`MyClass``' (role-with-extra-backtick)
+.. expect: Extra backtick in role: ':meth:``method`' (role-with-extra-backtick)
+
+This file contains roles with extra backtick that should be detected.
+
+* :pep:`594`: Remove the :mod:`!cgi`` and :mod:``!cgitb` modules
+
+* :func:`foo`` should be :func:`foo`
+
+* :class:`MyClass`` is wrong
+
+* :meth:``method` should be fixed