Add a central documentation pilot for PyPTO

.github/workflows/docs-site.yml

@@ -0,0 +1,144 @@
+name: Central documentation pilot
+
+on:
+  pull_request:
+    paths: ['scripts/docs_site.py', 'tests/test_docs_site.py', '.github/workflows/docs-site.yml', 'docs-theme/**', 'index.html']
+  push:
+    branches: [main]
+    paths: ['scripts/docs_site.py', '.github/workflows/docs-site.yml', 'docs-theme/**', 'index.html']
+  schedule:
+    - cron: '7,37 * * * *'
+  workflow_dispatch:
+    inputs:
+      source_repository:
+        description: 'Notification source repository (leave all source inputs empty for a manual build)'
+        type: string
+        default: ''
+      source_sha:
+        description: 'Source Docs run head SHA'
+        type: string
+        default: ''
+      source_run_id:
+        description: 'Completed source Docs run ID'
+        type: string
+        default: ''
+      source_run_attempt:
+        description: 'Completed source Docs run attempt'
+        type: string
+        default: ''
+
+permissions:
+  contents: read
+
+# PR validation cannot cancel or queue behind production publication.
+concurrency:
+  group: docs-site-${{ github.event_name == 'pull_request' && github.ref || 'publication' }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    if: >-
+      github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch' ||
+      (github.repository == 'hw-native-sys/hw-native-sys.github.io' && vars.DOCS_SITE_ENABLED == 'true')
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install pilot checks
+        run: python -m pip install -r tests/requirements.txt
+      - name: Test notification validation and publication guards
+        run: python -m pytest tests/test_docs_site.py -q
+      - name: Resolve successful upstream documentation snapshot
+        id: source
+        env:
+          GH_TOKEN: ${{ github.token }}
+          SOURCE_REPOSITORY: ${{ inputs.source_repository }}
+          SOURCE_SHA: ${{ inputs.source_sha }}
+          SOURCE_RUN_ID: ${{ inputs.source_run_id }}
+          SOURCE_RUN_ATTEMPT: ${{ inputs.source_run_attempt }}
+        run: python scripts/docs_site.py resolve --manifest .docs-build/manifest.json
+      - name: Check out selected PyPTO source
+        uses: actions/checkout@v4
+        with:
+          repository: hw-native-sys/pypto
+          ref: ${{ steps.source.outputs.source_sha }}
+          path: .docs-build/pypto
+          persist-credentials: false
+      - name: Supply the central theme
+        run: python scripts/docs_site.py prepare --manifest .docs-build/manifest.json --checkout .docs-build/pypto
+      - name: Install project documentation toolchain
+        run: python -m pip install -r .docs-build/pypto/docs/requirements.txt
+      - name: Check and build the selected source
+        working-directory: .docs-build/pypto
+        env:
+          DOCS_REF: ${{ steps.source.outputs.source_sha }}
+        run: |
+          source .claude/skills/testing/load-env.sh
+          python tests/lint/check_docs_nav.py
+          python tests/lint/check_docs_en_zh_parity.py
+          python tests/lint/check_docs_symbol_coverage.py
+          python tests/lint/check_op_docstring_parity.py
+          python -m pip check
+          python -m mkdocs build --strict
+      - name: Check generated pages and shared resources
+        run: python tests/docs_theme_compat.py check --site .docs-build/pypto/site --project pypto --page api/tile/index.html
+      - name: Assemble complete pilot artifact
+        run: python scripts/docs_site.py assemble --manifest .docs-build/manifest.json --checkout .docs-build/pypto --output .docs-build/public
+      - name: Upload inspectable pilot artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-site-pilot
+          path: .docs-build/public
+          include-hidden-files: true
+          if-no-files-found: error
+          retention-days: 14
+      - name: Upload Pages artifact for enabled publication
+        if: >-
+          github.repository == 'hw-native-sys/hw-native-sys.github.io' &&
+          github.ref == 'refs/heads/main' && github.event_name != 'pull_request' &&
+          vars.DOCS_SITE_PUBLISH == 'true'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: .docs-build/public
+
+  deploy:
+    needs: build
+    if: >-
+      github.repository == 'hw-native-sys/hw-native-sys.github.io' &&
+      github.ref == 'refs/heads/main' && github.event_name != 'pull_request' &&
+      vars.DOCS_SITE_PUBLISH == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - uses: actions/download-artifact@v4
+        with:
+          name: docs-site-pilot
+          path: .docs-build/public
+      - name: Reject superseded or unchanged publication
+        id: guard
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: python scripts/docs_site.py guard --manifest .docs-build/public/build-manifest.json
+      - uses: actions/configure-pages@v5
+        if: steps.guard.outputs.changed == 'true'
+      - uses: actions/deploy-pages@v4
+        id: deploy
+        if: steps.guard.outputs.changed == 'true'

.gitignore

@@ -1,2 +1,4 @@
 __pycache__/
 .pytest_cache/
+.docs-build/
+.venv/

docs/central-documentation.md

@@ -0,0 +1,68 @@
+# Central documentation pilot
+
+The website repository can build a successful PyPTO documentation snapshot and
+package it together with the homepage. The other four project sites retain
+their existing publishing workflows. Full-site search and their migration are
+separate follow-up changes; this pilot retains PyPTO's existing bilingual search.
+
+## Source and artifact contract
+
+`.github/workflows/docs-site.yml` selects a completed, successful run of
+`hw-native-sys/pypto`'s `.github/workflows/docs.yml` on `main`. The selected commit
+must still belong to upstream main history. A newer commit whose documentation
+CI has not succeeded is not substituted for it.
+
+The central workflow uses its own checkout's `docs-theme/`, runs PyPTO's
+documentation checks and strict build, and uploads `docs-site-pilot`. The
+artifact contains the homepage, its existing assets, `/pypto/`, and
+`build-manifest.json`. The manifest records both source revisions and the
+successful source run. Source links use the selected PyPTO SHA. No compiler,
+CANN installation, or device tests are required.
+
+## CI notifications
+
+PyPTO's `Notify central documentation` workflow runs after its Docs workflow
+completes successfully on upstream `main`. It dispatches `docs-site.yml` on the
+website's `main` with `source_repository`, `source_sha`, `source_run_id`, and
+`source_run_attempt`. The receiver verifies these claims through GitHub's API
+before selecting the latest eligible snapshot. Manual runs leave all four
+inputs empty.
+
+The notification workflow uses a GitHub App installation token scoped to this
+website repository with **Actions: write**. Its App ID and private key are
+provided to PyPTO through `DOCS_SITE_APP_ID` (Actions variable) and
+`DOCS_SITE_APP_PRIVATE_KEY` (Actions secret). A source repository's own
+`GITHUB_TOKEN` does not grant cross-repository write access.
+
+The notification listener must be merged into PyPTO's default branch, and the
+receiving workflow must be present on the website's default branch, before this
+event path can run. A successful notification means the build was requested;
+the central workflow and deployed manifest establish publication success.
+
+## Activation and ownership
+
+All switches are repository Actions variables and default to disabled:
+
+| Repository | Variable | Effect when enabled |
+| --- | --- | --- |
+| Website | `DOCS_SITE_ENABLED=true` | Enable automatic push and scheduled pilot builds; PR and manual builds already run |
+| PyPTO | `DOCS_SITE_NOTIFY_ENABLED=true` | Send notifications after successful upstream Docs runs |
+| Website | `DOCS_SITE_PUBLISH=true` | Permit the central main workflow to deploy its validated artifact |
+| PyPTO | `DOCS_SITE_PUBLISHER=central` | Stop the original Pages upload/deploy while preserving document validation |
+
+First enable artifact-only builds and notifications after configuring the App.
+Before enabling publication, verify the root-versus-project Pages routing
+handoff with an isolated route, select GitHub Actions as the website's Pages
+source, and preserve `www.pypto.ai` in its Pages settings. Coordinate PyPTO's
+publishing switch and Pages deactivation with that handoff. Changing its workflow
+variable alone does not remove the existing project Pages deployment.
+
+The production workflow is serialized separately from PR checks. Immediately
+before deployment it rejects a stale website workflow, superseded PyPTO source,
+changed source CI attempt, or an existing publication containing additional
+projects. Unchanged input revisions skip deployment. The scheduled check at
+minutes 7 and 37 uses the same successful-CI selection as notifications.
+
+Both default-branch workflow availability and App configuration are prerequisites
+for the live notification test. Unit tests and artifact builds do not establish
+that the App has been installed or that Pages routing has been handed over.