Merge branch 'main' into add-timestamps-to-index-hosted-attestations

Author: jku

.github/CODEOWNERS

@@ -1,6 +1,9 @@
 source/guides/github-actions-ci-cd-sample/* @webknjaz
 source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @webknjaz
 
+# Sphinx extension
+pug_sphinx_extensions/ @FFY00
+
 # build-details.json
 source/specifications/build-details/ @FFY00
 source/specifications/specs/build-details-*.json @FFY00

…s/schemas/build-details-v1.0.schema.json …s/schemas/build-details-v1.0.schema.jsonsource/specifications/schemas/build-details-v1.0.schema.json renamed to extra/specifications/schemas/build-details-v1.0.schema.json source/specifications/schemas/build-details-v1.0.schema.json renamed to extra/specifications/schemas/build-details-v1.0.schema.json

@@ -89,6 +89,7 @@ def linkcheck(session):
         "--keep-going",  # be strict
         "source",  # where the rst files are located
         "build",  # where to put the check output
+        *session.posargs,
     )
 
 

…fications/schemas/direct-url.schema.json …fications/schemas/direct-url.schema.jsonsource/specifications/schemas/direct-url.schema.json renamed to extra/specifications/schemas/direct-url.schema.json source/specifications/schemas/direct-url.schema.json renamed to extra/specifications/schemas/direct-url.schema.json

@@ -0,0 +1,86 @@
+import os
+import pathlib
+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.
+
+    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)
+        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}")
+    # 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
+
+
+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,
+    }

…pecifications/schemas/pylock.schema.json …pecifications/schemas/pylock.schema.jsonsource/specifications/schemas/pylock.schema.json renamed to extra/specifications/schemas/pylock.schema.json source/specifications/schemas/pylock.schema.json renamed to extra/specifications/schemas/pylock.schema.json

@@ -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",
@@ -83,6 +89,10 @@
     # https://plausible.io/packaging.python.org
     html_js_files.extend(_metrics_js_files)
 
+html_extra_path = [
+    "../extra",
+]
+
 # -- Options for HTML help output ------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-help-output
 
@@ -129,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/.*",
@@ -210,7 +219,6 @@
     "tox": ("https://tox.wiki/en/latest/", None),
     "twine": ("https://twine.readthedocs.io/en/stable/", None),
     "virtualenv": ("https://virtualenv.pypa.io/en/stable/", None),
-    "warehouse": ("https://warehouse.pypa.io/", None),
 }
 
 # -- Options for todo extension --------------------------------------------------------

noxfile.py

@@ -160,7 +160,7 @@ Glossary
 
         A string with valid SPDX license expression syntax,
         including one or more SPDX :term:`License Identifier`\(s),
-        which describes a :term:`Project`'s license(s)
+        which describes a :term:`Distribution Archive`'s license(s)
         and how they inter-relate.
         Examples:
         ``GPL-3.0-or-later``,

pug_sphinx_extensions/__init__.py

@@ -154,7 +154,7 @@ To just run the program without installing it permanently, use ``pipx run``, whi
 	$ pipx run --spec . greet --doctor
 
 This syntax is a bit impractical, however; as the name of the entry point we defined above does not match the package name,
-we need to state explicitly which executable script to run (even though there is only on in existence).
+we need to state explicitly which executable script to run (even though there is only one in existence).
 
 There is, however, a more practical solution to this problem, in the form of an entry point specific to ``pipx run``.
 The same can be defined as follows in :file:`pyproject.toml`:

source/conf.py

@@ -8,11 +8,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       with:
         persist-credentials: false
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: "3.x"
     - name: Install pypa/build
@@ -24,7 +24,7 @@ jobs:
     - name: Build a binary wheel and a source tarball
       run: python3 -m build
     - name: Store the distribution packages
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v5
       with:
         name: python-package-distributions
         path: dist/
@@ -44,7 +44,7 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v6
       with:
         name: python-package-distributions
         path: dist/
@@ -66,7 +66,7 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v6
       with:
         name: python-package-distributions
         path: dist/