Add nightly CI for documentation builds (#231)

Closes #228 and possibly also #219 

Needs a release of bloqade-circuit v0.2.0 first as it also updates the
examples to work with the new version.

Also, I'm checking the versions / commit hashes for the nightly builds
and cancel the jobs if nothing has changed. To do this, I'm using github
variables. Not sure if this is the best solution. If it is, then we'd
need to create the variables (the body can be empty to start with).
There are probably permission issues then as well since I don't think
the `GH_TOKEN` has permissions to set github variables and cancel jobs.

@Roger-luo @weinbe58 do you know a better solution for this?

Author: david-pl

.github/workflows/dev-doc-nightly.yml

@@ -0,0 +1,57 @@
+# This workflow pulls in the latest main branches of dependent packages and tries to build the documentation
+# so we can stay on top of issues with the examples when introducing changes
+name: Documentation
+on:
+  schedule:
+  - cron: 24 4 * * *
+concurrency:
+  group: ${{ github.workflow }}-${{ github.headref }}
+  cancel-in-progress: true
+
+jobs:
+  documentation:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          # Install a specific version of uv.
+          version: "0.5.1"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - name: Install Documentation dependencies
+        run: uv sync --group doc
+
+        # get latest dependencies from git directly
+      - name: clone the latest bloqade-circuit
+        id: clone_bloqade_circuit
+        uses: actions/checkout@v4
+        with:
+          repository: https://github.com/QuEraComputing/bloqade-circuit
+          path: '../bloqade-circuit'
+
+      - name: clone the latest bloqade-analog
+        id: clone_bloqade_analog
+        uses: actions/checkout@v4
+        with:
+          repository: https://github.com/QuEraComputing/bloqade-analog
+          path: '../bloqade-analog'
+
+      - name: add local repos as dependencies
+        run: uv add ../bloqade-circuit ../bloqade-analog
+
+      - name: Set up build cache
+        uses: actions/cache@v4
+        id: cache
+        with:
+          key: mkdocs-material-nightly-dev-${{ github.headref }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - name: Build documentation
+        env:
+          EXECUTE_NOTEBOOKS: "true"
+        run: |
+          uv run mkdocs build

.github/workflows/doc-nightly.yml

@@ -0,0 +1,39 @@
+# This workflow builds & deploys the documentation using the latest release versions of dependent packages
+# Main use is to detect issues / accidental breaking changes with patch releases of e.g. bloqade-circuit
+name: Documentation
+on:
+  schedule:
+  - cron: 12 4 * * 0
+concurrency:
+  group: ${{ github.workflow }}-${{ github.headref }}
+  cancel-in-progress: true
+
+jobs:
+  documentation:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          # Install a specific version of uv.
+          version: "0.5.1"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - name: Install Documentation dependencies
+        run: uv sync --group doc
+
+      - name: Set up build cache
+        uses: actions/cache@v4
+        id: cache
+        with:
+          key: mkdocs-material-nightly-${{ github.headref }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - name: Build documentation
+        env:
+          EXECUTE_NOTEBOOKS: "true"
+        run: |
+          uv run mkdocs build

_typos.toml

@@ -12,3 +12,6 @@ AttributeIDSupressMenu = "AttributeIDSupressMenu"
 Braket = "Braket"
 mch = "mch"
 IY = "IY"
+
+[files]
+extend-exclude = [".github/workflows/*"]

justfile

@@ -15,8 +15,9 @@ coverage-open:
 
 coverage: coverage-run coverage-xml coverage-report
 
-doc:
-    mkdocs serve
+doc FLAGS="":
+    mkdocs serve {{FLAGS}}
+
+doc-build FLAGS="":
+    mkdocs build {{FLAGS}}
 
-doc-build:
-    mkdocs build