pythongh-134895: Add sphinx-codeautolink to doc build

Author: cmarqu

Doc/_static/sphinx-codeautolink.css

@@ -0,0 +1,12 @@
+/*
+Style autolinks from Python example code to reference documentation
+(https://sphinx-codeautolink.readthedocs.io/en/latest/examples.html#custom-link-styles)
+*/
+
+.sphinx-codeautolink-a {
+    text-decoration-style: solid !important;
+    text-decoration-color: #aaa;
+}
+.sphinx-codeautolink-a:hover {
+    text-decoration-color: black;
+}

Doc/conf.py

@@ -36,6 +36,7 @@
     'sphinx.ext.coverage',
     'sphinx.ext.doctest',
     'sphinx.ext.extlinks',
+    'sphinx_codeautolink',
 ]
 
 # Skip if downstream redistributors haven't installed them
@@ -404,6 +405,9 @@
 # Additional static files.
 html_static_path = ['_static', 'tools/static']
 
+# Additional CSS files.
+html_css_files = ["sphinx-codeautolink.css"]
+
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'python' + release.replace('.', '')
 
@@ -413,6 +417,25 @@
 # Split pot files one per reST file
 gettext_compact = False
 
+# Options for automatic links from code examples to reference documentation.
+# (https://sphinx-codeautolink.readthedocs.io/)
+codeautolink_warn_on_missing_inventory = False
+codeautolink_warn_on_failed_resolve = False
+codeautolink_custom_blocks = {
+    # https://sphinx-codeautolink.readthedocs.io/en/latest/examples.html#doctest-code-blocks
+    "pycon3": "sphinx_codeautolink.clean_pycon",
+}
+
+suppress_warnings = [
+    # "codeautolink",
+    "codeautolink.import_star",
+    "codeautolink.match_block",
+    "codeautolink.match_name",
+    "codeautolink.parse_block",
+    "config.cache",
+]
+
+
 # Options for LaTeX output
 # ------------------------
 

Doc/constraints.txt

@@ -22,3 +22,6 @@ sphinxcontrib-serializinghtml<3
 
 # Direct dependencies of Jinja2 (Jinja is a dependency of Sphinx, see above)
 MarkupSafe<3
+
+# Direct dependencies of the sphinx-codeautolink extension
+beautifulsoup4<4.13.4

Doc/requirements.txt

@@ -13,6 +13,7 @@ blurb
 
 sphinxext-opengraph~=0.9.0
 sphinx-notfound-page~=1.0.0
+sphinx-codeautolink~=0.17.4
 
 # The theme used by the documentation is stored separately, so we need
 # to install that as well.

Misc/NEWS.d/next/Documentation/2025-05-29-17-35-28.gh-issue-134895.z7WboA.rst

@@ -0,0 +1,2 @@
+Add sphinx-codeautolink extension for reference links in code examples.
+Patch by Colin Marquardt.