docs: rework package file formats and doc generation

.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.yaml

@@ -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/argon2-cffi-bindings.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/blake3.yaml

@@ -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