CTLD/.github/workflows/docs.yml at develop · VEAF/CTLD · 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
name: Docs

# Build and publish the mkdocs site to the repo's gh-pages branch via mike.
#   develop            -> version/alias "dev"   (site default)
#   master             -> version/alias "latest"
#   published-vX.Y.Z   -> that exact version, and "latest" when it is a stable
#   published-vX.Y.Z-rcN -> that exact version, and NOT "latest"
#
# The tag jobs are what give the tool a versioned page to link to
# (FEAT-TOOL-VERSION-AND-DOCS). A pre-release deliberately does not move `latest`, the same
# discipline `release.yml` applies to the `published-latest` download pointer: an rc must not
# become what a newcomer reads by default.
on:
  push:
    branches: [develop, master]
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - '.github/workflows/docs.yml'
    tags:
      - 'published-v*'
  workflow_dispatch:

# mike rewrites gh-pages. A tag push and a develop push can land together (a release PR merges,
# then the tag goes up), and two concurrent rewrites lose one of the two deployments.
concurrency:
  group: docs-gh-pages
  cancel-in-progress: false

jobs:
  deploy:
    name: Build & deploy docs
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0   # mike needs the full gh-pages history

      - uses: actions/setup-python@v7
        with:
          python-version: '3.x'

      - name: Install docs dependencies
        run: pip install -r docs/requirements.txt

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

      - name: Deploy (develop -> dev)
        if: github.ref == 'refs/heads/develop'
        run: |
          mike deploy --push --update-aliases dev
          mike set-default --push dev

      - name: Deploy (master -> latest)
        if: github.ref == 'refs/heads/master'
        run: |
          mike deploy --push --update-aliases latest
          mike set-default --push latest

      - name: Deploy (tag -> that version, and latest when stable)
        if: startsWith(github.ref, 'refs/tags/published-v')
        run: |
          version="${GITHUB_REF_NAME#published-v}"
          # A semver pre-release suffix (a '-' in the version) marks an rc: publish the pages under
          # their own version but leave `latest` where it is. Same test release.yml uses.
          if [[ "$version" == *-* ]]; then
            echo "pre-release $version — publishing the version, not touching latest"
            mike deploy --push "$version"
          else
            echo "stable $version — publishing the version and moving latest"
            mike deploy --push --update-aliases "$version" latest
          fi
        shell: bash