make examples available via github pages on release (#128)

* remove useless test

* add infra to upload examples

* test example upload scripts

* add scripts, oops

Author: kevinyamauchi

.github/workflows/ci.yml

@@ -161,6 +161,8 @@ jobs:
       id-token: write
       # This permission allows writing releases
       contents: write
+      # This permission allows starting the docs workflow (last step)
+      actions: write
 
     steps:
       - uses: actions/checkout@v7
@@ -186,3 +188,29 @@ jobs:
         with:
           generate_release_notes: true
           files: './dist/*'
+
+      # The docs workflow publishes the example scripts of each release,
+      # pinned to that release, and leaves out a version that is not on PyPI
+      # (see plans/examples-distribution-v2.md). So wait until this one is
+      # there before starting it. The version is read from the sdist's name,
+      # which is the form PyPI knows it by (tag v0.1.0-rc1 is 0.1.0rc1).
+      - name: Wait for the release on PyPI
+        run: |
+          sdist=$(basename dist/cellier-*.tar.gz .tar.gz)
+          version="${sdist#cellier-}"
+          for _ in $(seq 30); do
+            if curl -fsS -o /dev/null "https://pypi.org/pypi/cellier/${version}/json"; then
+              echo "cellier ${version} is on PyPI"
+              exit 0
+            fi
+            sleep 10
+          done
+          echo "cellier ${version} did not appear on PyPI" >&2
+          exit 1
+
+      # The site can only be deployed from main, so the docs workflow is
+      # started there rather than run on this tag.
+      - name: Rebuild the docs site with this release's examples
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh workflow run docs.yml --repo "${{ github.repository }}" --ref main

.github/workflows/docs.yml

@@ -1,11 +1,18 @@
 name: Documentation
 
+# Builds the docs and adds the example scripts of every release, pinned to
+# that release (see plans/examples-distribution-v2.md). The whole site is
+# rebuilt on each run, so nothing is kept from the previous deploy.
+#
+# workflow_dispatch is how the release job in ci.yml starts this after a new
+# version is on PyPI.
+
 on:
   push:
     branches:
-      - master
       - main
   pull_request:
+  workflow_dispatch:
 
 permissions:
   contents: read
@@ -16,7 +23,10 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
+      # Full history, so the release tags are there to read the examples from.
       - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
       - uses: actions/configure-pages@v6
       - uses: actions/setup-python@v7
         with:
@@ -26,14 +36,26 @@ jobs:
       - run: pip install mkdocstrings mkdocstrings-python "griffe-pydantic>=1.3.1"
       - run: zensical build --clean
 
+      # Writes site/<tag>/examples/ and site/latest/examples/. On a pull
+      # request it also fails if an example in the branch could not be pinned.
+      - run: pip install packaging
+      - name: Add the released examples
+        run: >-
+          python scripts/example_upload/assemble_example_site.py site
+          ${{ github.event_name == 'pull_request' && '--working-tree-version 0.0.0' || '' }}
+
       - uses: actions/upload-pages-artifact@v5
         with:
           path: site
 
   deploy:
-    if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main')
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
     needs: build
     runs-on: ubuntu-latest
+    # One deploy at a time; a deploy that has started is left to finish.
+    concurrency:
+      group: pages
+      cancel-in-progress: false
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

pyproject.toml

@@ -101,8 +101,8 @@ examples = [
 dev-all = ["cellier[dev,test,pyside,examples,logging,remote,anywidget,graph]"]
 
 [project.urls]
-homepage = "https://github.com/kevinyamauchi/cellier"
-repository = "https://github.com/kevinyamauchi/cellier"
+homepage = "https://github.com/cellcanvas/cellier"
+repository = "https://github.com/cellcanvas/cellier"
 
 # Entry points
 # https://peps.python.org/pep-0621/#entry-points