ci_scripts: update_doc.py: add

Add a new version ofthe update_doc.py script from wheel_builder,
converted using Claude. Compared to the old one, we just generate,
parse, and update Markdown files directly for each package, and do it in
docs/packages/<package>.md instead of the longer
docs/source/packages/<package>.yaml.

AI-Generated: Uses Claude Code Sonnet 5

Signed-off-by: Trevor Gamblin <tgamblin@baylibre.com>

Author: threexc

ci_scripts/update_doc.py

@@ -0,0 +1,304 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: 2025 BayLibre, SAS
+# SPDX-FileCopyrightText: 2026 The RISE Project
+# SPDX-License-Identifier: MIT
+"""
+Extract metadata from a just-built riscv64 wheel, add or update the
+corresponding docs/packages/<name>.md page with the new version, and open a
+pull request with the change.
+
+Based on the script at:
+https://gitlab.com/riseproject/python/wheel_builder/-/blob/main/ci_scripts/update_doc.py
+
+That script wrote a small YAML file per package, which a separate stage later
+rendered into a Sphinx page. Since python-wheels' docs/packages/*.md pages are
+hand-off Markdown with no such intermediate source, this script edits the
+rendered page directly instead of re-introducing a YAML layer.
+"""
+
+import os
+import re
+import string
+import subprocess
+import sys
+import zipfile
+from email.message import Message
+from email.parser import Parser
+from pathlib import Path
+
+REPO = "riseproject-dev/python-wheels"
+REGISTRY_URL = "https://pypi.riseproject.dev/simple/"
+DOCS_DIR = Path("docs/packages")
+PACKAGES_FILE = Path("ci_scripts/packages.txt")
+ARTIFACTS_PATH = os.environ.get("ARTIFACTS_PATH", "dist")
+
+
+def find_wheel_file(path):
+    for file in Path(path).glob("*.whl"):
+        return file
+    return None
+
+
+def normalize_name(name):
+    """
+    https://packaging.python.org/en/latest/specifications/name-normalization/#name-normalization
+    """
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def normalize_label(label):
+    """
+    https://packaging.python.org/en/latest/specifications/well-known-project-urls/#label-normalization
+    """
+    chars_to_remove = string.punctuation + string.whitespace
+    removal_map = str.maketrans("", "", chars_to_remove)
+    return label.translate(removal_map).lower()
+
+
+def extract_license(message):
+    license = message.get("License-Expression")
+    if not license:
+        license = message.get("License", "Unknown")
+    return license
+
+
+def extract_source_code_url(message):
+    # Collect all "Project-URL" lines
+    project_urls = message.get_all("Project-URL", [])
+    well_known_labels = ["source", "repository", "sourcecode", "github"]
+
+    for entry in project_urls:
+        try:
+            label, url = map(str.strip, entry.split(",", 1))
+            if normalize_label(label) in well_known_labels:
+                return url
+        except ValueError:
+            continue  # skip malformed lines
+
+    # A lot of projects use homepage as source code url. Done in a second
+    # loop so a homepage entry appearing before a well-known source label
+    # doesn't win by accident.
+    for entry in project_urls:
+        try:
+            label, url = map(str.strip, entry.split(",", 1))
+            if normalize_label(label) == "homepage":
+                return url
+        except ValueError:
+            continue
+
+    return message.get("Home-page")  # deprecated fallback, may be None
+
+
+def extract_metadata_from_whl(whl_path):
+    """
+    Extract metadata according to https://packaging.python.org/en/latest/specifications/core-metadata/
+    """
+    with zipfile.ZipFile(whl_path, "r") as z:
+        metadata_file = next(f for f in z.namelist() if f.endswith("METADATA"))
+        content = z.read(metadata_file).decode()
+        message: Message = Parser().parsestr(content)
+        return {
+            "name": message.get("Name"),
+            "version": message.get("Version"),
+            "license": extract_license(message),
+            "source_code": extract_source_code_url(message),
+        }
+
+
+def find_patch_dir(slug, version):
+    """
+    Look for a `patches/<slug>/<version_tag>` directory as described in
+    docs/development.md, trying both a `v`-prefixed and bare version tag.
+    """
+    for tag in (f"v{version}", version):
+        candidate = Path("patches") / slug / tag
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def render_version_block(slug, version, license, patch_dir, *, latest):
+    label = f"{version} (latest)" if latest else version
+    open_attr = " open" if latest else ""
+    install_target = slug if latest else f"{slug}=={version}"
+
+    lines = [
+        f'<details markdown="1"{open_attr}>',
+        f"<summary><strong>{label}</strong></summary>",
+        "",
+        "```bash",
+        f"pip install {install_target} --index-url {REGISTRY_URL}",
+        "```",
+        "",
+        f"- **License:** {license}",
+    ]
+
+    if patch_dir is not None:
+        patch_url = f"https://github.com/{REPO}/tree/main/{patch_dir}"
+        lines.append(f"- **Patch applied for this version:** [{patch_url}]({patch_url})")
+
+    lines += ["</details>", ""]
+    return "\n".join(lines)
+
+
+def render_new_page(slug, display_name, version, license, source_code, patch_dir):
+    lines = [
+        "---",
+        f"title: {display_name}",
+        "layout: default",
+        "parent: Supported Packages",
+        "---",
+        "",
+        "<!-- Auto-generated by generate_packages_doc.py. Do not edit manually. -->",
+        "",
+        f"# {display_name}",
+        "",
+    ]
+    if source_code:
+        lines.append(f"- **Source Code:** [{source_code}]({source_code})")
+    lines += ["- **Supported versions:**", ""]
+    lines.append(render_version_block(slug, version, license, patch_dir, latest=True))
+    return "\n".join(lines).rstrip() + "\n"
+
+
+LATEST_DETAILS_RE = re.compile(
+    r'<details markdown="1" open>\n<summary><strong>([^<]+?)</strong></summary>'
+)
+
+
+def insert_new_version(content, slug, version, license, patch_dir):
+    """
+    Insert a new version block ahead of the current latest block, demoting the
+    previous latest block to a plain (non-open, non-"(latest)") entry.
+
+    Returns None if this exact version is already documented.
+    """
+    already_documented = re.search(
+        rf'<summary><strong>{re.escape(version)}( \(latest\))?</strong></summary>', content
+    )
+    if already_documented:
+        return None
+
+    match = LATEST_DETAILS_RE.search(content)
+    if match is None:
+        raise ValueError(f"No existing version blocks found for {slug}")
+
+    demoted_label = match.group(1).removesuffix(" (latest)")
+    demoted_header = f'<details markdown="1">\n<summary><strong>{demoted_label}</strong></summary>'
+    new_block = render_version_block(slug, version, license, patch_dir, latest=True)
+
+    # The demoted block's install command was rendered unpinned (it used to be
+    # latest); pin it to its own version now that it no longer is.
+    rest = content[match.end() :]
+    old_install = f"pip install {slug} --index-url {REGISTRY_URL}"
+    new_install = f"pip install {slug}=={demoted_label} --index-url {REGISTRY_URL}"
+    rest = rest.replace(old_install, new_install, 1)
+
+    return content[: match.start()] + new_block + "\n" + demoted_header + rest
+
+
+def add_index_entry(slug):
+    """Add a new package to the alphabetically sorted list in docs/packages/index.md."""
+    index_path = DOCS_DIR / "index.md"
+    lines = index_path.read_text().splitlines()
+    header_end = next(i for i, line in enumerate(lines) if line.startswith("- ["))
+    header, entries = lines[:header_end], lines[header_end:]
+    entries.append(f"- [{slug}]({slug}.html)")
+    entries = sorted(set(entries), key=lambda line: line.split("[", 1)[1].split("]", 1)[0].lower())
+    index_path.write_text("\n".join(header + entries) + "\n")
+
+
+def add_to_packages_file(slug):
+    lines = PACKAGES_FILE.read_text().splitlines()
+    header_end = next(i for i, line in enumerate(lines) if line and not line.startswith("#"))
+    header, entries = lines[:header_end], [line for line in lines[header_end:] if line]
+    entries = sorted(set(entries) | {slug}, key=str.casefold)
+    PACKAGES_FILE.write_text("\n".join(header + entries) + "\n")
+
+
+def git_run(*args):
+    subprocess.run(["git", *args], check=True)
+
+
+def configure_git_identity():
+    git_run("config", "user.name", "github-actions[bot]")
+    git_run("config", "user.email", "41898282+github-actions[bot]@users.noreply.github.com")
+
+
+def extract_pr_url(stdout):
+    for line in stdout.split("\n"):
+        line = line.strip()
+        if "github.com" in line and "/pull/" in line:
+            return line
+    return None
+
+
+def main():
+    whl_file = find_wheel_file(ARTIFACTS_PATH)
+    if not whl_file:
+        print(f"No .whl file found in {ARTIFACTS_PATH}")
+        sys.exit(1)
+
+    metadata = extract_metadata_from_whl(whl_file)
+    display_name = metadata["name"]
+    version = metadata["version"]
+    license = metadata["license"]
+    source_code = metadata["source_code"]
+
+    if not display_name or not version:
+        print("Name or version could not be extracted")
+        sys.exit(1)
+
+    slug = normalize_name(display_name)
+    patch_dir = find_patch_dir(slug, version)
+    page_path = DOCS_DIR / f"{slug}.md"
+    is_new = not page_path.exists()
+
+    if is_new:
+        page_path.write_text(
+            render_new_page(slug, display_name, version, license, source_code, patch_dir)
+        )
+    else:
+        updated = insert_new_version(page_path.read_text(), slug, version, license, patch_dir)
+        if updated is None:
+            print(f"{slug} {version} is already documented; nothing to do")
+            return
+        page_path.write_text(updated)
+
+    configure_git_identity()
+
+    branch = f"github-actions/{'add' if is_new else 'update'}-doc-for-{slug}"
+    git_run("switch", "-c", branch)
+    git_run("add", str(page_path))
+
+    if is_new:
+        add_index_entry(slug)
+        add_to_packages_file(slug)
+        git_run("add", str(DOCS_DIR / "index.md"), str(PACKAGES_FILE))
+        git_run("commit", "-s", "-m", f"docs: add {slug}\n\nAdd version {version}")
+    else:
+        git_run("commit", "-s", "-m", f"docs: update {slug}\n\nAdd version {version}")
+
+    git_run("push", "origin", branch)
+
+    result = subprocess.run(
+        [
+            "gh", "pr", "create", "--draft",
+            "--repo", REPO,
+            "--base", "main",
+            "--head", branch,
+            "--reviewer", "threexc,justeph",
+            "--title", f"docs: {'add' if is_new else 'update'} {slug}",
+            "--body",
+            "Automatically generated PR to document a newly published wheel. "
+            "Please review it carefully before merging.\n\n"
+            "If necessary, force-push this branch.",
+        ],
+        capture_output=True, text=True, check=True,
+    )
+    pr_url = extract_pr_url(result.stdout)
+    print(f"[+] Opened PR: {pr_url or '(URL not found in output)'}")
+
+
+if __name__ == "__main__":
+    main()