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..06f8b9efa99542 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,26 @@ # 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/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", + "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.