Add a shared theme for the PyPTO documentation sites

.github/workflows/docs-theme.yml

@@ -0,0 +1,119 @@
+name: Documentation theme
+
+on:
+  push:
+    branches: [main]
+    paths: ['index.html', 'docs-theme/**', 'tests/**', '.github/workflows/docs-theme.yml']
+  pull_request:
+    paths: ['index.html', 'docs-theme/**', 'tests/**', '.github/workflows/docs-theme.yml']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-theme-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  compatibility:
+    name: ${{ matrix.project }} (${{ matrix.sha }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      max-parallel: 2
+      matrix:
+        include:
+          - project: pypto
+            sha: 812628941a4ad118321e097ced984e9ec383203e
+            python: '3.11'
+            page: api/tile/index.html
+          - project: simpler
+            sha: 405b5bbda30f6d0f6167e4b2f283df2d42ca3443
+            python: '3.10'
+            page: user/reference/api/worker/index.html
+          - project: pypto-lib
+            sha: 216b497e4b7d8bb7b47e304e79fd59e01de2a2e9
+            python: '3.10'
+            page: get-started/first-kernel/index.html
+          - project: pypto-serving
+            sha: 967c839c22402cb3f23c7430129ce539a0accbdf
+            python: '3.11'
+            page: user-guide/online-serving/index.html
+          - project: pypto-tools
+            sha: 955cfcfc01c7028f0e9bef01b3fdabc04e90de9e
+            python: '3.11'
+            page: runtime/chip-swimlane/index.html
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: theme
+      - name: Check out fixed downstream snapshot
+        uses: actions/checkout@v4
+        with:
+          repository: hw-native-sys/${{ matrix.project }}
+          ref: ${{ matrix.sha }}
+          path: downstream
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install shared renderer
+        run: python -m pip install -r theme/docs-theme/constraints.txt
+      - name: Prepare candidate theme configuration
+        run: >-
+          python theme/tests/docs_theme_compat.py prepare
+          --repo downstream --project '${{ matrix.project }}'
+          --expected-sha '${{ matrix.sha }}'
+      - name: Install project documentation plugins
+        # Toolkit's temporary requirements test the 9.7.7 candidate explicitly;
+        # no upstream dependency file or source config is changed.
+        run: >-
+          python -m pip install -c theme/docs-theme/constraints.txt
+          -r downstream/requirements-theme-compat.txt
+      - name: Record tested source and toolchain
+        run: |
+          git -C downstream rev-parse HEAD
+          python --version
+          python -m pip freeze
+          python -m pip check
+      - name: Run existing documentation checks and strict build
+        working-directory: downstream
+        env:
+          DOCS_REF: ${{ matrix.sha }}
+        run: |
+          if [ -f .claude/skills/testing/load-env.sh ]; then
+            source .claude/skills/testing/load-env.sh
+          fi
+          for check in check_docs_nav check_public_docs check_docs_en_zh_parity check_docs_symbol_coverage check_op_docstring_parity; do
+            if [ -f "tests/lint/$check.py" ]; then
+              python "tests/lint/$check.py"
+            fi
+          done
+          if [ -f tests/docs/test_repo_links.py ]; then
+            python -m unittest discover -s tests/docs -v
+          fi
+          mkdocs build --strict -f mkdocs.theme-compat.yml --site-dir site-theme
+      - name: Validate rendered branding, links, and assets
+        run: >-
+          python theme/tests/docs_theme_compat.py check
+          --site downstream/site-theme --project '${{ matrix.project }}'
+          --page '${{ matrix.page }}'
+      - name: Upload review preview
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-theme-${{ matrix.project }}-${{ matrix.sha }}
+          path: downstream/site-theme
+          retention-days: 7
+      - name: Install browser checks
+        if: matrix.project == 'pypto'
+        run: |
+          python -m pip install -r theme/tests/requirements.txt
+          python -m playwright install --with-deps chromium
+      - name: Check homepage and bilingual PyPTO in Chromium
+        if: matrix.project == 'pypto'
+        env:
+          PYPTO_DOCS_SITE: ${{ github.workspace }}/downstream/site-theme
+        run: python -m pytest theme/tests/test_browser_theme.py -q

.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+.pytest_cache/

docs-theme/base.yml

@@ -0,0 +1,51 @@
+# Paths to the overrides directory belong in the consuming mkdocs.yml.
+theme:
+  name: material
+  font: false
+  logo: assets/images/pypto.svg
+  favicon: assets/images/pypto.svg
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.indexes
+    - navigation.top
+    - navigation.footer
+    - content.code.copy
+    - content.action.edit
+    - search.suggest
+    - search.highlight
+    - toc.follow
+  # A mapping avoids Material's per-project palette selector. The shared
+  # selector supports system/light/dark with one preference across projects.
+  palette:
+    scheme: default
+    primary: custom
+    accent: custom
+
+extra_css:
+  - assets/stylesheets/brand.css
+  - assets/stylesheets/docs.css
+
+extra:
+  homepage: https://www.pypto.ai/
+  pypto_projects:
+    - id: pypto
+      name: PyPTO
+      url: https://www.pypto.ai/pypto/
+      languages: [en, zh]
+    - id: simpler
+      name: Simpler
+      url: https://www.pypto.ai/simpler/
+      languages: [en]
+    - id: pypto-lib
+      name: PyPTO Lib
+      url: https://www.pypto.ai/pypto-lib/
+      languages: [en]
+    - id: pypto-serving
+      name: PyPTO Serving
+      url: https://www.pypto.ai/pypto-serving/
+      languages: [en]
+    - id: pypto-tools
+      name: PyPTO Toolkit
+      url: https://www.pypto.ai/pypto-tools/
+      languages: [en, zh]

docs-theme/constraints.txt

@@ -0,0 +1,3 @@
+# Shared renderer versions. Project-specific plugins remain in each repository.
+mkdocs==1.6.1
+mkdocs-material==9.7.7

docs-theme/overrides/assets/javascripts/preferences.js

@@ -0,0 +1,96 @@
+/* One preference for the homepage, project roots, and translated pages. */
+(() => {
+  "use strict";
+  if (window.PyPTOTheme) return;
+
+  const key = "pypto:color-scheme";
+  const modes = new Set(["system", "light", "dark"]);
+  const system = window.matchMedia("(prefers-color-scheme: dark)");
+  function readMode(fallback = "system") {
+    try {
+      const saved = window.localStorage.getItem(key);
+      return modes.has(saved) ? saved : "system";
+    } catch {
+      // Storage may be unavailable in private or embedded browser contexts.
+      return fallback;
+    }
+  }
+  let mode = readMode();
+
+  function apply() {
+    const dark = mode === "dark" || (mode === "system" && system.matches);
+    document.documentElement.dataset.pyptoTheme = dark ? "dark" : "light";
+    document.documentElement.classList.remove("no-js");
+    if (document.body) {
+      document.body.dataset.mdColorScheme = dark ? "slate" : "default";
+    }
+    document.querySelectorAll("[data-pypto-theme-select]").forEach(select => {
+      select.value = mode;
+    });
+  }
+
+  function closeProjects(restoreFocus = false) {
+    document.querySelectorAll(".pypto-project-switcher[open]").forEach(menu => {
+      menu.open = false;
+      if (restoreFocus) menu.querySelector("summary").focus();
+    });
+  }
+
+  function updatePage() {
+    apply();
+    closeProjects();
+    const search = document.querySelector("[data-md-component='search-query']");
+    const project = document.querySelector("[data-pypto-project-name]");
+    if (search && project) {
+      const name = project.dataset.pyptoProjectName;
+      const label = document.documentElement.lang.startsWith("zh") ? `搜索 ${name}` : `Search ${name}`;
+      search.placeholder = label;
+      search.setAttribute("aria-label", label);
+    }
+  }
+
+  let connected = false;
+  window.PyPTOTheme = {
+    apply,
+    connectMaterial() {
+      if (!connected && window.document$) {
+        connected = true;
+        window.document$.subscribe(updatePage);
+      }
+      updatePage();
+    }
+  };
+
+  apply();
+  document.addEventListener("DOMContentLoaded", updatePage);
+  document.addEventListener("change", event => {
+    if (!event.target.matches("[data-pypto-theme-select]")) return;
+    const selected = event.target.value;
+    if (!modes.has(selected)) return;
+    mode = selected;
+    try {
+      window.localStorage.setItem(key, mode);
+    } catch {
+      // Keep the selection for this page even when it cannot be persisted.
+    }
+    apply();
+  });
+  document.addEventListener("click", event => {
+    if (!event.target.closest(".pypto-project-switcher")) closeProjects();
+  });
+  document.addEventListener("keydown", event => {
+    if (event.key === "Escape") closeProjects(true);
+  });
+  window.addEventListener("storage", event => {
+    if (event.key !== key && event.key !== null) return;
+    mode = modes.has(event.newValue) ? event.newValue : "system";
+    apply();
+  });
+  window.addEventListener("pageshow", () => {
+    mode = readMode(mode);
+    apply();
+  });
+  system.addEventListener("change", () => {
+    if (mode === "system") apply();
+  });
+})();

docs-theme/overrides/assets/stylesheets/brand.css

@@ -0,0 +1,78 @@
+/* Shared by the organization homepage and every documentation build. */
+:root {
+  color-scheme: light;
+  --pypto-background: #f7f8fc;
+  --pypto-surface: #ffffff;
+  --pypto-text: #192039;
+  --pypto-muted: #59627a;
+  --pypto-line: #dfe3ee;
+  --pypto-accent: #4352c7;
+  --pypto-featured: #f0f2ff;
+  --pypto-shadow: 0 12px 32px rgb(25 32 57 / 6%);
+  --pypto-font: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  --pypto-code-font: ui-monospace, SFMono-Regular, Consolas, "Liberation Mono", monospace;
+}
+
+:root[data-pypto-theme="dark"] {
+  color-scheme: dark;
+  --pypto-background: #10121b;
+  --pypto-surface: #191d2b;
+  --pypto-text: #edf0ff;
+  --pypto-muted: #aab3cc;
+  --pypto-line: #343b53;
+  --pypto-accent: #a8b2ff;
+  --pypto-featured: #20263e;
+  --pypto-shadow: 0 12px 32px rgb(0 0 0 / 18%);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-pypto-theme]) {
+    color-scheme: dark;
+    --pypto-background: #10121b;
+    --pypto-surface: #191d2b;
+    --pypto-text: #edf0ff;
+    --pypto-muted: #aab3cc;
+    --pypto-line: #343b53;
+    --pypto-accent: #a8b2ff;
+    --pypto-featured: #20263e;
+    --pypto-shadow: 0 12px 32px rgb(0 0 0 / 18%);
+  }
+}
+
+.pypto-theme-control {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  color: var(--pypto-muted);
+  font: 14px var(--pypto-font);
+}
+
+.pypto-theme-control select {
+  min-height: 40px;
+  max-width: 100%;
+  padding: 6px 8px;
+  color: var(--pypto-text);
+  background: var(--pypto-surface);
+  border: 1px solid var(--pypto-line);
+  border-radius: 8px;
+  font: inherit;
+  cursor: pointer;
+}
+
+.pypto-theme-control select:focus-visible {
+  outline: 3px solid var(--pypto-accent);
+  outline-offset: 3px;
+}
+
+.pypto-visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+.no-js .pypto-theme-control { display: none; }