From e3e8cbb30b1ba514a41fe6aa85964cf9d184c797 Mon Sep 17 00:00:00 2001 From: Colin Marquardt Date: Thu, 29 May 2025 17:45:55 +0200 Subject: [PATCH 1/2] gh-134895: Add sphinx-codeautolink to doc build --- Doc/_static/sphinx-codeautolink.css | 12 ++++++++++ Doc/conf.py | 23 +++++++++++++++++++ Doc/constraints.txt | 3 +++ Doc/requirements.txt | 1 + ...-05-29-17-35-28.gh-issue-134895.z7WboA.rst | 2 ++ 5 files changed, 41 insertions(+) create mode 100644 Doc/_static/sphinx-codeautolink.css create mode 100644 Misc/NEWS.d/next/Documentation/2025-05-29-17-35-28.gh-issue-134895.z7WboA.rst diff --git a/Doc/_static/sphinx-codeautolink.css b/Doc/_static/sphinx-codeautolink.css new file mode 100644 index 00000000000000..586b180b9c6fc9 --- /dev/null +++ b/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; +} diff --git a/Doc/conf.py b/Doc/conf.py index 56594f32c6d02d..ea86164755a7e5 100644 --- a/Doc/conf.py +++ b/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 # ------------------------ diff --git a/Doc/constraints.txt b/Doc/constraints.txt index 29cd4be1d3c8db..787baebe271715 100644 --- a/Doc/constraints.txt +++ b/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 diff --git a/Doc/requirements.txt b/Doc/requirements.txt index 32ff8f74d05bb6..1a35fa708fb3a1 100644 --- a/Doc/requirements.txt +++ b/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. diff --git a/Misc/NEWS.d/next/Documentation/2025-05-29-17-35-28.gh-issue-134895.z7WboA.rst b/Misc/NEWS.d/next/Documentation/2025-05-29-17-35-28.gh-issue-134895.z7WboA.rst new file mode 100644 index 00000000000000..174a84eb042cde --- /dev/null +++ b/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. From 365b0b305daa037caa4ad93e8796761566d956f9 Mon Sep 17 00:00:00 2001 From: Colin Marquardt Date: Fri, 30 May 2025 16:44:42 +0200 Subject: [PATCH 2/2] Address review comments --- Doc/conf.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Doc/conf.py b/Doc/conf.py index ea86164755a7e5..06f8b9efa99542 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -419,14 +419,15 @@ # 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_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", + # https://sphinx-codeautolink.readthedocs.io/en/latest/reference.html#cleanup-functions + "pycon": "sphinx_codeautolink.clean_pycon", } suppress_warnings = [ + # https://sphinx-codeautolink.readthedocs.io/en/latest/reference.html#warning-types # "codeautolink", "codeautolink.import_star", "codeautolink.match_block",