From 266de83e5559a7da95a881f8d91129a103a15275 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filipe=20La=C3=ADns?= Date: Wed, 12 Nov 2025 13:37:02 +0000 Subject: [PATCH 1/3] Restore linkcheck for specs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Filipe Laíns --- pug_sphinx_extensions/__init__.py | 76 +++++++++++++++++++++++++++++++ source/conf.py | 10 ++-- 2 files changed, 82 insertions(+), 4 deletions(-) create mode 100644 pug_sphinx_extensions/__init__.py diff --git a/pug_sphinx_extensions/__init__.py b/pug_sphinx_extensions/__init__.py new file mode 100644 index 000000000..ae495bb60 --- /dev/null +++ b/pug_sphinx_extensions/__init__.py @@ -0,0 +1,76 @@ +import os +import urllib + +import sphinx.application +import sphinx.util.logging + + +DOMAIN = 'packaging.python.org' + + +logger = sphinx.util.logging.getLogger(__name__) + + +def resolve_local_html_link(app: sphinx.application.Sphinx, url_path: str) -> str: + """Takes path of a link pointing an HTML render of the current project, + and returns local path of the referenced document. + + Support links to renders from both the `html` and `dirhtml` builders. + + Example: + + .. code-block:: python + + >>> resolve_local_html_link('https://packaging.python.org/en/latest/flow/') + '{srcdir}/flow.rst' + >>> resolve_local_html_link('https://packaging.python.org/en/latest/flow.html') + '{srcdir}/flow.rst' + >>> resolve_local_html_link('https://packaging.python.org/en/latest/specifications/schemas/') + '{srcdir}/specifications/schemas/index.rst' + >>> resolve_local_html_link('https://packaging.python.org/en/latest/specifications/schemas/build-details-v1.0.schema.json') + '{html_extra_path0}/specifications/schemas/build-details-v1.0.schema.json' + + """ + # Search for document in html_extra_path + for entry in app.config.html_extra_path: + candidate = (app.confdir / entry / url_path).resolve() + if candidate.is_dir(): + candidate = candidate / 'index.html' + if candidate.exists(): + return os.fspath(candidate) + # Convert html path to source path + url_path = url_path.removesuffix('/') # Normalize + if url_path.endswith('.html'): + document = url_path.removesuffix('.html') + elif (candidate := f'{url_path}/index') in app.project.docnames: + document = candidate + else: + document = url_path + return app.env.doc2path(document) + + +def rewrite_local_uri(app: sphinx.application.Sphinx, uri: str) -> str: + """Replace remote URIs targeting https://packaging.python.org/en/latest/... + with local ones, so that local changes are taken into account by linkcheck. + """ + local_uri = uri + parsed = urllib.parse.urlparse(uri) + if parsed.hostname == DOMAIN and parsed.path.startswith('/en/latest/'): + document = parsed.path.removeprefix('/en/latest/') + local_uri = resolve_local_html_link(app, document) + logger.verbose( + f'{uri!s} is a remote URL that points to local sources, ' + 'replacing it with a local URL in linkcheck to take new changes ' + 'into account (pass -vv for more info)' + ) + logger.debug(f'Replacing linkcheck URL {uri!r} with {local_uri!r}') + return local_uri + + +def setup(app: sphinx.application.Sphinx) -> dict[str, bool]: + app.connect('linkcheck-process-uri', rewrite_local_uri) + + return { + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/source/conf.py b/source/conf.py index d18faf662..ccb828b6e 100644 --- a/source/conf.py +++ b/source/conf.py @@ -2,6 +2,11 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information import os +import pathlib +import sys + +_ROOT = pathlib.Path(__file__).resolve().parent.parent +sys.path.append(os.fspath(_ROOT)) # Some options are only enabled for the main packaging.python.org deployment builds RTD_BUILD = bool(os.getenv("READTHEDOCS")) @@ -22,6 +27,7 @@ root_doc = "index" extensions = [ + "pug_sphinx_extensions", "sphinx.ext.extlinks", "sphinx.ext.intersphinx", "sphinx.ext.todo", @@ -133,7 +139,6 @@ linkcheck_ignore = [ r"http://localhost:\d+", - r"https://packaging\.python\.org/en/latest/specifications/schemas/.*", r"https://test\.pypi\.org/project/example-package-YOUR-USERNAME-HERE", r"https://pypi\.org/manage/.*", r"https://test\.pypi\.org/manage/.*", @@ -162,9 +167,6 @@ # https://github.com/pypa/packaging.python.org/issues/1744 r"https://pypi\.org/", ] -linkcheck_exclude_documents = [ - "specifications/schemas/index", -] # -- Options for extlinks ---------------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html#configuration From 5cad3680c2d845c8edd53e416eaaeb3b972aefc5 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 12 Nov 2025 14:23:22 +0000 Subject: [PATCH 2/3] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- pug_sphinx_extensions/__init__.py | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/pug_sphinx_extensions/__init__.py b/pug_sphinx_extensions/__init__.py index ae495bb60..82abe6997 100644 --- a/pug_sphinx_extensions/__init__.py +++ b/pug_sphinx_extensions/__init__.py @@ -5,7 +5,7 @@ import sphinx.util.logging -DOMAIN = 'packaging.python.org' +DOMAIN = "packaging.python.org" logger = sphinx.util.logging.getLogger(__name__) @@ -35,14 +35,14 @@ def resolve_local_html_link(app: sphinx.application.Sphinx, url_path: str) -> st for entry in app.config.html_extra_path: candidate = (app.confdir / entry / url_path).resolve() if candidate.is_dir(): - candidate = candidate / 'index.html' + candidate = candidate / "index.html" if candidate.exists(): return os.fspath(candidate) # Convert html path to source path - url_path = url_path.removesuffix('/') # Normalize - if url_path.endswith('.html'): - document = url_path.removesuffix('.html') - elif (candidate := f'{url_path}/index') in app.project.docnames: + url_path = url_path.removesuffix("/") # Normalize + if url_path.endswith(".html"): + document = url_path.removesuffix(".html") + elif (candidate := f"{url_path}/index") in app.project.docnames: document = candidate else: document = url_path @@ -55,22 +55,22 @@ def rewrite_local_uri(app: sphinx.application.Sphinx, uri: str) -> str: """ local_uri = uri parsed = urllib.parse.urlparse(uri) - if parsed.hostname == DOMAIN and parsed.path.startswith('/en/latest/'): - document = parsed.path.removeprefix('/en/latest/') + if parsed.hostname == DOMAIN and parsed.path.startswith("/en/latest/"): + document = parsed.path.removeprefix("/en/latest/") local_uri = resolve_local_html_link(app, document) logger.verbose( - f'{uri!s} is a remote URL that points to local sources, ' - 'replacing it with a local URL in linkcheck to take new changes ' - 'into account (pass -vv for more info)' + f"{uri!s} is a remote URL that points to local sources, " + "replacing it with a local URL in linkcheck to take new changes " + "into account (pass -vv for more info)" ) - logger.debug(f'Replacing linkcheck URL {uri!r} with {local_uri!r}') + logger.debug(f"Replacing linkcheck URL {uri!r} with {local_uri!r}") return local_uri def setup(app: sphinx.application.Sphinx) -> dict[str, bool]: - app.connect('linkcheck-process-uri', rewrite_local_uri) + app.connect("linkcheck-process-uri", rewrite_local_uri) return { - 'parallel_read_safe': True, - 'parallel_write_safe': True, + "parallel_read_safe": True, + "parallel_write_safe": True, } From 1a0e01d3f55121e8a2675f3b3de81ac304fa1c72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filipe=20La=C3=ADns?= Date: Fri, 14 Nov 2025 22:41:54 +0000 Subject: [PATCH 3/3] Resolve local relative links to html_extra_path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Filipe Laíns --- pug_sphinx_extensions/__init__.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/pug_sphinx_extensions/__init__.py b/pug_sphinx_extensions/__init__.py index 82abe6997..00d91da3c 100644 --- a/pug_sphinx_extensions/__init__.py +++ b/pug_sphinx_extensions/__init__.py @@ -1,4 +1,5 @@ import os +import pathlib import urllib import sphinx.application @@ -52,9 +53,12 @@ def resolve_local_html_link(app: sphinx.application.Sphinx, url_path: str) -> st def rewrite_local_uri(app: sphinx.application.Sphinx, uri: str) -> str: """Replace remote URIs targeting https://packaging.python.org/en/latest/... with local ones, so that local changes are taken into account by linkcheck. + + Additionally, resolve local relative links to html_extra_path. """ local_uri = uri parsed = urllib.parse.urlparse(uri) + # Links to https://packaging.python.org/en/latest/... if parsed.hostname == DOMAIN and parsed.path.startswith("/en/latest/"): document = parsed.path.removeprefix("/en/latest/") local_uri = resolve_local_html_link(app, document) @@ -64,6 +68,12 @@ def rewrite_local_uri(app: sphinx.application.Sphinx, uri: str) -> str: "into account (pass -vv for more info)" ) logger.debug(f"Replacing linkcheck URL {uri!r} with {local_uri!r}") + # Local relative links + if not parsed.scheme and not parsed.netloc and parsed.path: + full_path = pathlib.Path(app.env.docname).parent / parsed.path + local_uri = resolve_local_html_link(app, os.fspath(full_path)) + if local_uri != uri: + logger.verbose(f"Local linkcheck URL {uri!r} resolved as {local_uri!r}") return local_uri