[3.13] GH-121970: Use Ruff to check and format the docs tools (GH-122018) (#122023)

GH-121970: Use Ruff to check and format the docs tools (GH-122018)
(cherry picked from commit 40855f3ab8)

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Alex Waygood <Alex.Waygood@gmail.com>

Doc/tools/check-warnings.py

@@ -2,6 +2,7 @@
 """
 Check the output of running Sphinx in nit-picky mode (missing references).
 """
+
 from __future__ import annotations
 
 import argparse
@@ -206,7 +207,9 @@ def annotate_diff(
 
 
 def fail_if_regression(
-    warnings: list[str], files_with_expected_nits: set[str], files_with_nits: set[str]
+    warnings: list[str],
+    files_with_expected_nits: set[str],
+    files_with_nits: set[str],
 ) -> int:
     """
     Ensure some files always pass Sphinx nit-picky mode (no missing references).
@@ -252,17 +255,11 @@ def fail_if_new_news_nit(warnings: list[str], threshold: int) -> int:
     """
     Ensure no warnings are found in the NEWS file before a given line number.
     """
-    news_nits = (
-        warning
-        for warning in warnings
-        if "/build/NEWS:" in warning
-    )
+    news_nits = (warning for warning in warnings if "/build/NEWS:" in warning)
 
     # Nits found before the threshold line
     new_news_nits = [
-        nit
-        for nit in news_nits
-        if int(nit.split(":")[1]) <= threshold
+        nit for nit in news_nits if int(nit.split(":")[1]) <= threshold
     ]
 
     if new_news_nits:
@@ -311,7 +308,8 @@ def main(argv: list[str] | None = None) -> int:
     exit_code = 0
 
     wrong_directory_msg = "Must run this script from the repo root"
-    assert Path("Doc").exists() and Path("Doc").is_dir(), wrong_directory_msg
+    if not Path("Doc").exists() or not Path("Doc").is_dir():
+        raise RuntimeError(wrong_directory_msg)
 
     with Path("Doc/sphinx-warnings.txt").open(encoding="UTF-8") as f:
         warnings = f.read().splitlines()
@@ -339,7 +337,9 @@ def main(argv: list[str] | None = None) -> int:
         )
 
     if args.fail_if_improved:
-        exit_code += fail_if_improved(files_with_expected_nits, files_with_nits)
+        exit_code += fail_if_improved(
+            files_with_expected_nits, files_with_nits
+        )
 
     if args.fail_if_new_news_nit:
         exit_code += fail_if_new_news_nit(warnings, args.fail_if_new_news_nit)

Doc/tools/extensions/glossary_search.py

@@ -17,7 +17,11 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-def process_glossary_nodes(app: Sphinx, doctree: nodes.document, _docname: str) -> None:
+def process_glossary_nodes(
+    app: Sphinx,
+    doctree: nodes.document,
+    _docname: str,
+) -> None:
     if app.builder.format != 'html' or app.builder.embedded:
         return
 
@@ -34,7 +38,7 @@ def process_glossary_nodes(app: Sphinx, doctree: nodes.document, _docname: str)
             rendered = app.builder.render_partial(definition)
             terms[term.lower()] = {
                 'title': term,
-                'body': rendered['html_body']
+                'body': rendered['html_body'],
             }
 
 
@@ -42,7 +46,7 @@ def write_glossary_json(app: Sphinx, _exc: Exception) -> None:
     if not getattr(app.env, 'glossary_terms', None):
         return
 
-    logger.info(f'Writing glossary.json', color='green')
+    logger.info('Writing glossary.json', color='green')
     dest = Path(app.outdir, '_static', 'glossary.json')
     dest.parent.mkdir(exist_ok=True)
     dest.write_text(json.dumps(app.env.glossary_terms), encoding='utf-8')

Doc/tools/extensions/lexers/asdl_lexer.py

@@ -28,7 +28,7 @@ class ASDLLexer(RegexLexer):
             # Keep in line with ``builtin_types`` from Parser/asdl.py.
             # ASDL's 4 builtin types are
             # constant, identifier, int, string
-            ('constant|identifier|int|string', Name.Builtin),
+            ("constant|identifier|int|string", Name.Builtin),
             (r"attributes", Name.Builtin),
             (
                 _name + _text_ws + "(=)",