Documentation for gLayout

.github/workflows/docs.yml

@@ -0,0 +1,168 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+  # Rebuild after the last stage in the chain (DRC -> LVS + ngspice) so the
+  # deployed tables track the newest run. This must match the `name:` field in
+  # sim.yml, not its filename.
+  workflow_run:
+    workflows: ["Automated: Cell ngspice"]
+    types: [completed]
+
+# actions:read is required for download-artifact to reach a *different*
+# workflow run (same reason lvs.yml declares it). Without it the artifact
+# downloads fail with "Resource not accessible by integration".
+permissions:
+  contents: read
+  actions: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    # A cancelled upstream run has partial or no artifacts; nothing to publish.
+    if: ${{ github.event_name != 'workflow_run' || github.event.workflow_run.conclusion != 'cancelled' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install sphinx furo myst-parser
+          pip install -e . || echo "package install failed; API reference will be omitted"
+
+      # Pull the runners' summary.json files so the tables show the newest run
+      # rather than the committed sample. Best-effort: a stage with no artifact
+      # simply gets no column in the matrix.
+      #
+      # The ngspice run triggered this build, so its artifacts hang off
+      # github.event.workflow_run. DRC and LVS are sibling runs, so they are
+      # fetched by name from the branch instead.
+      - name: Download ngspice results
+        if: github.event_name == 'workflow_run'
+        continue-on-error: true
+        uses: actions/download-artifact@v4
+        with:
+          pattern: sim-*
+          path: _artifacts
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      # DRC and LVS belong to sibling runs (both are "Cell DRC" descendants),
+      # so their run ids are not on this event. dawidd6's action resolves the
+      # latest successful run of a named workflow on a branch, which the
+      # built-in download-artifact cannot do.
+      - name: Download DRC and LVS results
+        if: github.event_name == 'workflow_run'
+        continue-on-error: true
+        uses: dawidd6/action-download-artifact@v6
+        with:
+          name_is_regexp: true
+          name: '(drc|lvs)-.*'
+          branch: ${{ github.event.workflow_run.head_branch || 'main' }}
+          path: _artifacts
+          if_no_artifact_found: warn
+
+      # Artifacts unpack as _artifacts/<stage>-<pdk>/... — reshape into the
+      # <stage>_results/<pdk>/summary.json layout conf.py expects.
+      - name: Assemble results tree
+        if: github.event_name == 'workflow_run'
+        continue-on-error: true
+        run: |
+          shopt -s nullglob
+          for dir in _artifacts/*-*/; do
+            base=$(basename "$dir")
+            stage=${base%%-*}
+            pdk=${base#*-}
+            [ -f "$dir/summary.json" ] || continue
+            mkdir -p "${stage}_results/$pdk"
+            cp "$dir/summary.json" "${stage}_results/$pdk/summary.json"
+            echo "staged ${stage}_results/$pdk/summary.json"
+          done
+
+      - name: Check README tables against the run
+        if: github.event_name == 'workflow_run'
+        continue-on-error: true
+        run: python tools/render_results.py --results-root . --target README.md --check
+
+      - name: Stage _site/ from web/
+        run: |
+          rm -rf _site && mkdir _site
+          cp -r web/. _site/
+          # Serve the summaries from the deployed origin so the dashboard needs
+          # no cross-origin fetch.
+          shopt -s nullglob
+          for f in ./*_results/*/summary.json; do
+            mkdir -p "_site/$(dirname "$f")"
+            cp "$f" "_site/$f"
+          done
+          cat > _site/live/config.js <<'JS'
+          window.GLAYOUT_LIVE = {
+            resultsBase: "../",
+            pdks: ["sky130", "gf180"]
+          };
+          JS
+
+      - name: Build Sphinx site (root)
+        env:
+          GLAYOUT_ENABLE_INTERSPHINX: '1'
+          GLAYOUT_RUN_COMMIT: ${{ github.sha }}
+          GLAYOUT_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          sphinx-build -b html --keep-going sphinx _site
+          touch _site/.nojekyll
+
+      - name: Upload site for review
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: _site
+
+      - name: Configure Pages
+        if: >-
+          github.event_name != 'pull_request' &&
+          (github.event_name != 'workflow_run' ||
+           github.event.workflow_run.head_branch == 'main')
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        if: >-
+          github.event_name != 'pull_request' &&
+          (github.event_name != 'workflow_run' ||
+           github.event.workflow_run.head_branch == 'main')
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  pages:
+    needs: build
+    # Deploy only from main. A workflow_run event reports github.ref as the
+    # default branch regardless of which branch actually ran, so the real
+    # branch has to come from the triggering run's head_branch — otherwise a
+    # PR branch's results would be published to the live site.
+    if: >-
+      github.event_name != 'pull_request' &&
+      (github.event_name != 'workflow_run' ||
+       github.event.workflow_run.head_branch == 'main')
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v4

.gitignore

@@ -281,4 +281,20 @@ tutorial/*.svg
 tutorial/*.lyrdb
 tutorial/fvf.gds
 tutorial/out.gds
-tutorial/out.svg
+tutorial/out.svg
+
+# Docs build output
+_site/
+_artifacts/
+# Leading slash anchors these to the repo root, so they do not also match the
+# committed sample data under sphinx/data/sample/.
+/drc_results/
+/lvs_results/
+/sim_results/
+sphinx/api_modules.rst
+sphinx/_autosummary/
+*.raw
+*.lyrdb
+
+# The committed sample data is not runner output.
+!sphinx/data/sample/**