deeperfly/.github/workflows/docs.yml at main · NeLy-EPFL/deeperfly · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
# Publish the MkDocs site to GitHub Pages, one version per branch.
#
# `main` publishes as the version in pyproject.toml (e.g. `0.2.0`) and takes the
# `stable` alias, which the site's default redirect points at. `dev` publishes as
# `dev`. Both live side by side under the site root, and Material's version
# selector moves between them:
#
#     https://nely-epfl.github.io/deeperfly/          -> redirects to stable
#     https://nely-epfl.github.io/deeperfly/stable/   -> the last release
#     https://nely-epfl.github.io/deeperfly/dev/      -> the dev branch
#     https://nely-epfl.github.io/deeperfly/0.2.0/    -> that release, pinned forever
#
# ONE-TIME SETUP, and the site will 404 until it is done: Settings -> Pages ->
# "Build and deployment" -> Source must be **"Deploy from a branch"**, branch
# `gh-pages`, folder `/ (root)`. This replaces the previous "GitHub Actions"
# source: mike works by COMMITTING built sites to the gh-pages branch rather than
# by uploading an artifact, which is what lets several versions coexist. The
# branch is created by the first successful run of this workflow.
name: docs

on:
  push:
    branches: [main, dev]
    paths:
      - "docs/**"
      - "examples/**"          # the example notebooks are rendered into the site
      - "mkdocs.yml"
      - "src/**"               # mkdocstrings renders the API reference from it
      - "CHANGELOG.md"         # included into docs/changelog.md
      - "pyproject.toml"       # the `docs` dependency group, and the version
      - "uv.lock"
      - ".github/workflows/docs.yml"
  workflow_dispatch:

# mike PUSHES to gh-pages, so this needs write access to the repo rather than the
# pages/id-token pair an artifact deploy needs.
permissions:
  contents: write

# gh-pages is a single branch two branches can race to push. Serialize, and never
# cancel a run that may be mid-push.
concurrency:
  group: docs-gh-pages
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          # mike rewrites gh-pages history, so it needs the real history, not a
          # depth-1 clone.
          fetch-depth: 0

      - uses: astral-sh/setup-uv@v5

      - name: Configure git for mike's commits
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

      # `mike deploy` builds without --strict, so the gate is run explicitly
      # first: mkdocstrings resolves every ::: identifier at build time, so a
      # renamed or deleted documented symbol fails here instead of publishing a
      # page with a hole in it. A failure stops the deploy, leaving the currently
      # published version untouched.
      - name: Build (strict) as the gate
        run: uv run --group docs mkdocs build --strict

      - name: Publish dev
        if: github.ref == 'refs/heads/dev'
        run: uv run --group docs mike deploy --push --update-aliases dev

      # The release version comes from pyproject.toml so a version bump publishes
      # a new pinned version on its own. `stable` is re-pointed at it in the same
      # command, and set-default keeps the site root redirecting at `stable`
      # rather than at a version number that will age.
      - name: Publish release
        if: github.ref == 'refs/heads/main'
        run: |
          version=$(uv run --group docs python -c \
            "import tomllib, pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
          echo "publishing $version (alias: stable)"
          uv run --group docs mike deploy --push --update-aliases "$version" stable
          uv run --group docs mike set-default --push stable