docs: rework package file formats and doc generation (#171)

* docs: packages: replace markdown files with YAML

This makes python-wheels more consistent with the original package docs'
pattern in wheel_builder.

* ci_scripts: check_versions.py: fix docs path

We were still using the old docs/source/packages path, rather than
the docs/packages path in python-wheels.

* docs: packages: generate_packages_doc.py: fix paths, registry URLs

Use simpler logic and the new proxy URL for the package registry when
generating docs.

* docs: add .gitignore for .md files

These are generated for documentation deployment, but they shouldn't be
committed to the repository anymore, only deployed by a workflow.

* workflows: docs: add

Create a custom workflow for deploying our documentation to GitHub
Pages. This allows us to retain the original YAML-to-documentation
generation process we've used in the past, and stops us from relying
solely on files already being on the main branch for documentation build
and review.

We have to incorporate two new community actions for this:

1. `peaceiris/actions-gh-pages`, for deploying the actual docs using a
   `gh-pages` branch
2. `rossjrew/pr-preview-action`, for creating docs previews so we're
   able to review the changes before merge. Comments will be posted on
   the PR providing preview links.

The `gh-pages` branch also requires a `.nojekyll` file at the project
root to avoid a manual rebuild, which can take a lot of time. Finally,
the `Deploy from a branch` option in the Pages setting needs to point at
`root/`, not `docs/` or it won't find the `.nojekyll` file.

* docs: infrastructure.md: document Pages configuration for docs.yml workflow

---------

AI-Generated: Uses Claude Sonnet 5

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

Author: threexc

.github/workflows/docs.yml

@@ -0,0 +1,113 @@
+# SPDX-FileCopyrightText: 2026 The RISE Project
+# SPDX-License-Identifier: MIT
+
+name: Build and deploy documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+  workflow_dispatch:
+
+concurrency:
+  group: docs-${{ github.ref }}
+
+jobs:
+  preview:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        if: github.event.action != 'closed'
+        with:
+          python-version: '3'
+
+      - name: Install package doc generator dependencies
+        if: github.event.action != 'closed'
+        run: pip install -r docs/requirements.txt
+
+      - name: Generate package pages from YAML
+        if: github.event.action != 'closed'
+        run: python docs/packages/generate_packages_doc.py
+
+      - name: Compute preview baseurl
+        if: github.event.action != 'closed'
+        id: preview_baseurl
+        run: |
+          base=$(python3 -c "import yaml; print(yaml.safe_load(open('docs/_config.yml'))['baseurl'])")
+          echo "value=${base}/pr-preview/pr-${{ github.event.number }}" >> "$GITHUB_OUTPUT"
+
+      - uses: ruby/setup-ruby@v1
+        if: github.event.action != 'closed'
+        with:
+          ruby-version: '3.3'
+
+      # actions/jekyll-build-pages has no way to override _config.yml's
+      # hardcoded baseurl, but a preview is served one path segment deeper
+      # (.../pr-preview/pr-<N>/) than the production site, so it needs its
+      # own baseurl or every internal link/asset would point at production.
+      - name: Build with Jekyll
+        if: github.event.action != 'closed'
+        run: |
+          # jekyll-remote-theme only fetches just-the-docs' layouts/assets;
+          # its own gem dependencies (jekyll-seo-tag, jekyll-include-cache,
+          # rake) still have to be installed separately.
+          gem install jekyll jekyll-remote-theme jekyll-seo-tag jekyll-include-cache rake --no-document
+          jekyll build --source docs --destination _site \
+            --baseurl "${{ steps.preview_baseurl.outputs.value }}"
+
+      # Auto-detects deploy vs. removal from the pull_request event action,
+      # so this same step both publishes updates and tears down the preview
+      # when the PR is closed.
+      #
+      # wait-for-pages-deployment is deliberately left at its default
+      # (false): on classic "deploy from a branch" Pages, its lookup against
+      # the legacy Pages Builds API doesn't reliably find an exact-commit
+      # build within its hardcoded 180s timeout, and that timeout is a hard,
+      # non-configurable `exit 1` that fails the whole step/PR check even
+      # when the preview deployed and is serving correctly. A link that's
+      # occasionally not live for a few seconds is a smaller problem than a
+      # misleading red X on an otherwise-working PR.
+      - name: Deploy or remove PR preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: ./_site
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3'
+
+      - name: Install package doc generator dependencies
+        run: pip install -r docs/requirements.txt
+
+      - name: Generate package pages from YAML
+        run: python docs/packages/generate_packages_doc.py
+
+      - name: Build with Jekyll
+        uses: actions/jekyll-build-pages@v1
+        with:
+          source: ./docs
+          destination: ./_site
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./_site
+          keep_files: true

ci_scripts/check_versions.py

@@ -166,7 +166,7 @@ def create_deprecation_pr(package: str, reason: str) -> Optional[str]:
         git_run("fetch", "origin")
         git_run("switch", "main")
 
-        yaml_file = Path(f"docs/source/packages/{package}.yaml")
+        yaml_file = Path(f"docs/packages/{package}.yaml")
         if not yaml_file.exists():
             print(f"    [!] YAML file for {package} does not exist")
             return None

docs/.gitignore

@@ -0,0 +1 @@
+packages/*.md

docs/infrastructure.md

@@ -66,3 +66,25 @@ regenerated by a project administrator/owner.
 |-------|-------|------|--------|----------|--------|
 | `PYTHON_CI_GROUP_TOKEN` | Group ([Python](https://gitlab.com/riseproject/python)) | Maintainer | `api`, `read_api`, `read_repository`, `write_repository` | MR pipeline triggers, auto updates/checks | 1 year (April 19th, 2027) |
 | `rise-github-package-registry` | Repository deploy token ([wheel_builder](https://gitlab.com/riseproject/python/wheel_builder/-/settings/repository#js-deploy-tokens)) | n/a (deploy token) | `read_package_registry`, `write_package_registry` | Push wheels GitHub → GitLab package registry | 1 year (June 29th, 2027) |
+
+## GitHub Pages Configuration
+
+The `.github/workflows/docs.yml` workflow handles building and deploying
+documentation, including providing previews of the docs on a per-PR basis. For
+this to work correctly, the following settings need to be configured under
+`Settings -> Pages -> Build and deployment` in the repository:
+
+1. `Source` should be set to `Deploy from a branch`
+2. `Branch` should be set to `gh-pages` `/(root)`
+
+When this is configured, any changes touching the `docs` folder will trigger a
+docs build, where upon completion the `rossjrw/pr-preview-action` will
+automatically comment on the PR with a link looking like:
+
+```
+https://riseproject-dev.github.io/python-wheels/pr-preview/pr-171/
+```
+
+Note that the `gh-pages` branch should be automatically created by the
+workflows, but if not it must be created manually with an empty `.nojekyll` file
+in the project root to avoid long rebuild times.

docs/packages/aiohttp.md

@@ -0,0 +1,21 @@
+deprecated:
+package-name: aiohttp
+source-code: https://github.com/aio-libs/aiohttp
+license: Apache-2.0
+warning: |
+  We disable the tests in tests/autobahn/test_autobahn as they depend on
+  docker_on_whales and we don't want to be testing docker builds as part of
+  the pipeline.
+
+  We also disable a flaky uvloop test, and tests that contain the following
+  patterns, involving consistent failures related to networking or permissions:
+
+  - test_no_warnings
+  - test_static_directory_without_read_permission
+  - test_static_file_without_read_permission
+  - test_uvloop_secure_https_proxy
+versions:
+  - version: 3.11.18
+    patched:
+  - version: 3.12.14
+    patched:

docs/packages/aiohttp.yaml

@@ -0,0 +1,6 @@
+package-name: argon2-cffi-bindings
+source-code: https://github.com/hynek/argon2-cffi-bindings
+license: MIT/CC0(libargon2)
+versions:
+  - version: 21.2.0
+  - version: 25.1.0

docs/packages/argon2-cffi-bindings.md

@@ -0,0 +1,9 @@
+deprecated:
+package-name: blake3
+source-code: https://github.com/oconnor663/blake3-py
+license: CC0-1.0 OR Apache-2.0
+versions:
+  - version: 1.0.5
+  - version: 1.0.6
+  - version: 1.0.7
+  - version: 1.0.8