docs.yml

# Two separable things live here: *validating* the documentation, which runs on
# every push and every pull request, and *publishing* it to GitHub Pages, which
# only works on a repository that has Pages enabled.
#
# The upload and deploy are gated on `has_pages` so the validation half is
# useful on a fork, or on any checkout where Pages is off: those runs skip
# publishing instead of failing at it, and start publishing on their own if
# Pages is later enabled, with no edit to this file.
name: Docs

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  image-tools:
    uses: ./.github/workflows/tc002-image-tools.yml

  build:
    needs: image-tools
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-python@v6
        with:
          python-version: "3.12"
          cache: pip
          cache-dependency-path: requirements-docs.txt
      - run: pip install -r requirements-docs.txt
      - uses: actions/download-artifact@v8.0.1
        with:
          name: tc002-image-tools
          path: docs/assets/tc002/image/
      - name: Prepare the TC002 browser installation package
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          tag=$(gh release view --json tagName -q .tagName 2>/dev/null || true)
          if [ -z "$tag" ]; then exit 0; fi
          mkdir -p docs/firmware/tc002
          gh release download "$tag" --pattern 'usb-awtrix-ng-tc002.zip' --dir docs/firmware/tc002 || true
          python - "$tag" <<'PY'
          import hashlib, json, pathlib, sys, zipfile
          sys.path.insert(0, "tools/tc002/install")
          from constants import MAX_ARCHIVE_BYTES, PRODUCTION_TARGET
          root = pathlib.Path("docs/firmware/tc002")
          package = root / "usb-awtrix-ng-tc002.zip"
          if package.exists():
              data = package.read_bytes()
              if not 0 < len(data) <= MAX_ARCHIVE_BYTES:
                  raise SystemExit("TC002 browser package exceeds its size limit")
              with zipfile.ZipFile(package) as archive:
                  entry = archive.getinfo("browser-manifest.json")
                  if entry.file_size > 16384 or entry.compress_type != zipfile.ZIP_STORED:
                      raise SystemExit("Invalid TC002 browser manifest")
                  manifest = json.loads(archive.read(entry))
              if manifest.get("target") != PRODUCTION_TARGET or manifest.get("dirty") is not False:
                  raise SystemExit("Not a clean TC002 browser package")
              record = {"version": manifest["version"], "asset": package.name, "size": len(data),
                        "sha256": hashlib.sha256(data).hexdigest()}
              (root / "index.json").write_text(json.dumps(record), encoding="utf-8")
          else:
              print("No TC002 browser package is published for this release.")
          PY
      # The browser flasher on getting-started/flashing.md fetches the firmware
      # from this site, not from the releases page: release assets carry no
      # Access-Control-Allow-Origin header, so a page on github.io cannot read
      # them. They are copied in here instead, and never committed.
      #
      # This build is what publishes them, so a release only reaches the flasher
      # once the docs are rebuilt -- which is why the release job in ci.yml
      # triggers this workflow.
      - name: Fetch the firmware the browser flasher serves
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          tag=$(gh release view --json tagName -q .tagName 2>/dev/null || true)
          if [ -z "$tag" ]; then
            echo "::warning::No published release -- the browser flasher will report that no firmware is available."
            exit 0
          fi
          mkdir -p docs/firmware
          # A release from before the USB install images existed carries none of
          # them, and that is not a reason to stop publishing documentation.
          # Since v1.0.16 they come bundled in usb-awtrix-ng.zip; before that
          # they were loose usb-*.bin, and factory-*.bin up to v1.0.14 -- all
          # three shapes are fetched, the flasher wants the unpacked files.
          gh release download "$tag" --pattern 'usb-awtrix-ng.zip' --dir docs/firmware || true
          if [ -f docs/firmware/usb-awtrix-ng.zip ]; then
            unzip -o docs/firmware/usb-awtrix-ng.zip -d docs/firmware
            rm docs/firmware/usb-awtrix-ng.zip
          fi
          gh release download "$tag" --pattern 'usb-*.bin' --dir docs/firmware || true
          gh release download "$tag" --pattern 'factory-*.bin' --dir docs/firmware || true
          if ! ls docs/firmware/*.bin >/dev/null 2>&1; then
            echo "::warning::Release $tag carries no USB install image -- the browser flasher will report that no firmware is available."
            exit 0
          fi
          python - "$tag" <<'PY'
          import json, os, sys
          names = sorted(f for f in os.listdir("docs/firmware") if f.endswith(".bin"))
          with open("docs/firmware/index.json", "w") as f:
              json.dump({"version": sys.argv[1], "assets": names}, f, indent=1)
          print("web flasher serves %s: %s" % (sys.argv[1], ", ".join(names)))
          PY
      - name: Prepare browser firmware updates
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          tag=$(gh release view --json tagName -q .tagName 2>/dev/null || true)
          if [ -z "$tag" ]; then exit 0; fi
          mkdir -p "docs/firmware/ota/$tag"
          gh release download "$tag" --pattern 'firmware-awtrix-ng*.bin' --pattern 'awtrix-ng-tc002.awup' --dir "docs/firmware/ota/$tag"
          python - "$tag" <<'PY'
          import hashlib, json, pathlib, sys
          tag = sys.argv[1]
          root = pathlib.Path("docs/firmware/ota")
          assets = {}
          for name in ("firmware-awtrix-ng.bin", "firmware-awtrix-ng-s3-octal.bin", "firmware-awtrix-ng-s3-quad.bin"):
              data = (root / tag / name).read_bytes()
              assets[name] = {"size": len(data), "sha256": hashlib.sha256(data).hexdigest()}
          tc002 = root / tag / "awtrix-ng-tc002.awup"
          if tc002.exists():
              data = tc002.read_bytes()
              assets[tc002.name] = {"size": len(data), "sha256": hashlib.sha256(data).hexdigest()}
          (root / "index.json").write_text(json.dumps({"version": tag, "assets": assets}), encoding="utf-8")
          PY
      # One documentation per clock plus the landing page, assembled into site/.
      # Each build runs with --strict; the script also fails on broken in-page
      # anchors (mkdocs reports those at INFO level only), on text that names
      # another clock, and on redirects or cross-links into missing pages.
      - name: Build the site for every clock
        run: python tools/docs/build_site.py
      - name: Upload the Pages artifact
        if: github.event.repository.has_pages
        uses: actions/upload-pages-artifact@v3
        with:
          path: site

  deploy:
    if: github.ref == 'refs/heads/main' && github.event.repository.has_pages
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4