GH-121970: Use Ruff to check and format the docs tools

.pre-commit-config.yaml

@@ -2,6 +2,10 @@ repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.3.4
     hooks:
+      - id: ruff
+        name: Run Ruff on Doc/
+        args: [--exit-non-zero-on-fix]
+        files: ^Doc/
       - id: ruff
         name: Run Ruff on Lib/test/
         args: [--exit-non-zero-on-fix]

Doc/.ruff.toml

@@ -0,0 +1,55 @@
+target-version = "py312"  # align with the version in oldest_supported_sphinx
+fix = true
+output-format = "full"
+extend-exclude = [
+    "includes/*",
+    "tools/extensions/c_annotations.py",
+    "tools/extensions/escape4chm.py",
+    "tools/extensions/patchlevel.py",
+    "tools/extensions/pyspecific.py",
+]
+
+[lint]
+preview = true
+select = [
+    "C4",  # flake8-comprehensions
+    "B",   # flake8-bugbear
+    "E",   # pycodestyle
+    "EM",  # flake8-errmsg
+    "F",   # pyflakes
+    "FA",  # flake8-future-annotations
+    "FLY", # flynt
+    "FURB",# refurb
+    "G",   # flake8-logging-format
+    "I",   # isort
+    "LOG", # flake8-logging
+    "N",   # pep8-naming
+    "PERF",# perflint
+    "PGH", # pygrep-hooks
+    "PT",  # flake8-pytest-style
+    "TCH", # flake8-type-checking
+    "UP",  # pyupgrade
+    "W",   # pycodestyle
+]
+
+[lint.per-file-ignores]
+"tools/extensions/lexers/peg_lexer.py" =[
+    "E501",
+]
+"tools/extensions/c_annotations.py" =[
+    "E501",
+]
+"tools/extensions/pyspecific.py" =[
+    "E501",
+]
+
+[format]
+preview = true
+quote-style = "single"
+exclude = [
+    "tools/extensions/lexers/*",
+    "tools/extensions/c_annotations.py",
+    "tools/extensions/escape4chm.py",
+    "tools/extensions/patchlevel.py",
+    "tools/extensions/pyspecific.py",
+]

Doc/conf.py

@@ -9,6 +9,7 @@
 import os
 import sys
 import time
+
 sys.path.append(os.path.abspath('tools/extensions'))
 sys.path.append(os.path.abspath('includes'))
 
@@ -30,20 +31,20 @@
 
 # Skip if downstream redistributors haven't installed them
 try:
-    import notfound.extension
+    import notfound.extension  # NoQA: F401
 except ImportError:
     pass
 else:
     extensions.append('notfound.extension')
 try:
-    import sphinxext.opengraph
+    import sphinxext.opengraph  # NoQA: F401
 except ImportError:
     pass
 else:
     extensions.append('sphinxext.opengraph')
 
 
-doctest_global_setup = '''
+doctest_global_setup = """
 try:
     import _tkinter
 except ImportError:
@@ -53,7 +54,7 @@
 import warnings
 warnings.simplefilter('error')
 del warnings
-'''
+"""
 
 manpages_url = 'https://manpages.debian.org/{path}'
 
@@ -63,7 +64,8 @@
 
 # We look for the Include/patchlevel.h file in the current Python source tree
 # and replace the values accordingly.
-import patchlevel
+import patchlevel  # NoQA: E402
+
 version, release = patchlevel.get_version_info()
 
 rst_epilog = f"""
@@ -298,7 +300,8 @@
 
 # Disable Docutils smartquotes for several translations
 smartquotes_excludes = {
-    'languages': ['ja', 'fr', 'zh_TW', 'zh_CN'], 'builders': ['man', 'text'],
+    'languages': ['ja', 'fr', 'zh_TW', 'zh_CN'],
+    'builders': ['man', 'text'],
 }
 
 # Avoid a warning with Sphinx >= 4.0
@@ -319,30 +322,32 @@
     'collapsiblesidebar': True,
     'issues_url': '/bugs.html',
     'license_url': '/license.html',
-    'root_include_title': False   # We use the version switcher instead.
+    'root_include_title': False,  # We use the version switcher instead.
 }
 
-if os.getenv("READTHEDOCS"):
-    html_theme_options["hosted_on"] = '<a href="https://about.readthedocs.com/">Read the Docs</a>'
+if os.getenv('READTHEDOCS'):
+    html_theme_options['hosted_on'] = (
+        '<a href="https://about.readthedocs.com/">Read the Docs</a>'
+    )
 
 # Override stylesheet fingerprinting for Windows CHM htmlhelp to fix GH-91207
 # https://github.com/python/cpython/issues/91207
 if any('htmlhelp' in arg for arg in sys.argv):
     html_style = 'pydoctheme.css'
-    print("\nWARNING: Windows CHM Help is no longer supported.")
-    print("It may be removed in the future\n")
+    print('\nWARNING: Windows CHM Help is no longer supported.')
+    print('It may be removed in the future\n')
 
 # Short title used e.g. for <title> HTML tags.
 html_short_title = f'{release} Documentation'
 
 # Deployment preview information
 # (See .readthedocs.yml and https://docs.readthedocs.io/en/stable/reference/environment-variables.html)
-repository_url = os.getenv("READTHEDOCS_GIT_CLONE_URL")
+repository_url = os.getenv('READTHEDOCS_GIT_CLONE_URL')
 html_context = {
-    "is_deployment_preview": os.getenv("READTHEDOCS_VERSION_TYPE") == "external",
-    "repository_url": repository_url.removesuffix(".git") if repository_url else None,
-    "pr_id": os.getenv("READTHEDOCS_VERSION"),
-    "enable_analytics": os.getenv("PYTHON_DOCS_ENABLE_ANALYTICS"),
+    'is_deployment_preview': os.getenv('READTHEDOCS_VERSION_TYPE') == 'external',
+    'repository_url': repository_url.removesuffix('.git') if repository_url else None,
+    'pr_id': os.getenv('READTHEDOCS_VERSION'),
+    'enable_analytics': os.getenv('PYTHON_DOCS_ENABLE_ANALYTICS'),
 }
 
 # This 'Last updated on:' timestamp is inserted at the bottom of every page.
@@ -388,15 +393,15 @@
 
 latex_elements = {
     # For the LaTeX preamble.
-    'preamble': r'''
+    'preamble': r"""
 \authoraddress{
   \sphinxstrong{Python Software Foundation}\\
   Email: \sphinxemail{[email protected]}
 }
 \let\Verbatim=\OriginalVerbatim
 \let\endVerbatim=\endOriginalVerbatim
 \setcounter{tocdepth}{2}
-''',
+""",
     # The paper size ('letter' or 'a4').
     'papersize': 'a4',
     # The font size ('10pt', '11pt' or '12pt').
@@ -407,30 +412,52 @@
 # (source start file, target name, title, author, document class [howto/manual]).
 _stdauthor = 'Guido van Rossum and the Python development team'
 latex_documents = [
-    ('c-api/index', 'c-api.tex',
-     'The Python/C API', _stdauthor, 'manual'),
-    ('extending/index', 'extending.tex',
-     'Extending and Embedding Python', _stdauthor, 'manual'),
-    ('installing/index', 'installing.tex',
-     'Installing Python Modules', _stdauthor, 'manual'),
-    ('library/index', 'library.tex',
-     'The Python Library Reference', _stdauthor, 'manual'),
-    ('reference/index', 'reference.tex',
-     'The Python Language Reference', _stdauthor, 'manual'),
-    ('tutorial/index', 'tutorial.tex',
-     'Python Tutorial', _stdauthor, 'manual'),
-    ('using/index', 'using.tex',
-     'Python Setup and Usage', _stdauthor, 'manual'),
-    ('faq/index', 'faq.tex',
-     'Python Frequently Asked Questions', _stdauthor, 'manual'),
-    ('whatsnew/' + version, 'whatsnew.tex',
-     'What\'s New in Python', 'A. M. Kuchling', 'howto'),
+    ('c-api/index', 'c-api.tex', 'The Python/C API', _stdauthor, 'manual'),
+    (
+        'extending/index',
+        'extending.tex',
+        'Extending and Embedding Python',
+        _stdauthor,
+        'manual',
+    ),
+    (
+        'installing/index',
+        'installing.tex',
+        'Installing Python Modules',
+        _stdauthor,
+        'manual',
+    ),
+    (
+        'library/index',
+        'library.tex',
+        'The Python Library Reference',
+        _stdauthor,
+        'manual',
+    ),
+    (
+        'reference/index',
+        'reference.tex',
+        'The Python Language Reference',
+        _stdauthor,
+        'manual',
+    ),
+    ('tutorial/index', 'tutorial.tex', 'Python Tutorial', _stdauthor, 'manual'),
+    ('using/index', 'using.tex', 'Python Setup and Usage', _stdauthor, 'manual'),
+    ('faq/index', 'faq.tex', 'Python Frequently Asked Questions', _stdauthor, 'manual'),
+    (
+        'whatsnew/' + version,
+        'whatsnew.tex',
+        "What's New in Python",
+        'A. M. Kuchling',
+        'howto',
+    ),
 ]
 # Collect all HOWTOs individually
-latex_documents.extend(('howto/' + fn[:-4], 'howto-' + fn[:-4] + '.tex',
-                        '', _stdauthor, 'howto')
-                       for fn in os.listdir('howto')
-                       if fn.endswith('.rst') and fn != 'index.rst')
+latex_documents.extend(
+    ('howto/' + fn[:-4], 'howto-' + fn[:-4] + '.tex', '', _stdauthor, 'howto')
+    for fn in os.listdir('howto')
+    if fn.endswith('.rst') and fn != 'index.rst'
+)
 
 # Documents to append as an appendix to all manuals.
 latex_appendices = ['glossary', 'about', 'license', 'copyright']
@@ -458,8 +485,7 @@
     'test($|_)',
 ]
 
-coverage_ignore_classes = [
-]
+coverage_ignore_classes = []
 
 # Glob patterns for C source files for C API coverage, relative to this directory.
 coverage_c_path = [
@@ -476,7 +502,7 @@
 # The coverage checker will ignore all C items whose names match these regexes
 # (using re.match) -- the keys must be the same as in coverage_c_regexes.
 coverage_ignore_c_items = {
-#    'cfunction': [...]
+    #    'cfunction': [...]
 }
 
 
@@ -534,10 +560,10 @@
 # mapping unique short aliases to a base URL and a prefix.
 # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
 extlinks = {
-    "cve": ("https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-%s", "CVE-%s"),
-    "cwe": ("https://cwe.mitre.org/data/definitions/%s.html", "CWE-%s"),
-    "pypi": ("https://pypi.org/project/%s/", "%s"),
-    "source": (SOURCE_URI, "%s"),
+    'cve': ('https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-%s', 'CVE-%s'),
+    'cwe': ('https://cwe.mitre.org/data/definitions/%s.html', 'CWE-%s'),
+    'pypi': ('https://pypi.org/project/%s/', '%s'),
+    'source': (SOURCE_URI, '%s'),
 }
 extlinks_detect_hardcoded_links = True