signalwire-python/.github/workflows/reference-docs.yml at main · signalwire/signalwire-python · 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
# API reference docs (pilot).
#
# Builds the SignalWire Python SDK API reference (MkDocs Material + mkdocstrings)
# and publishes it to this repo's OWN GitHub Pages via mike (versioned):
#   https://signalwire.github.io/signalwire-python/
#
# PILOT triggers: workflow_dispatch + push to the pilot branch. This is NOT
# gated on releases yet.
#   PRODUCTION (later): switch the trigger to `v*` tags so each release version
#   is deployed and `latest` is re-aliased. See the commented block below.
#
# MANUAL REPO SETTING REQUIRED to go live (one-time, in the GitHub UI):
#   Settings -> Pages -> Build and deployment -> Source = "Deploy from a branch"
#   -> Branch = `gh-pages` / `(root)`. mike pushes the built site there.
name: reference-docs

on:
  workflow_dispatch:
  push:
    branches:
      - docs/api-reference-pilot

  # --- PRODUCTION trigger (enable when promoting out of the pilot) ------------
  # push:
  #   tags:
  #     - "v*"

permissions:
  contents: write   # mike pushes the built site to the gh-pages branch

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0   # mike needs full history + the gh-pages branch

      - uses: actions/setup-python@v6
        with:
          python-version: "3.11"

      - name: Install SDK (editable) + doc toolchain
        run: |
          python -m pip install --upgrade pip
          pip install -r reference/requirements.txt
          pip install -e .

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

      - name: Generate API pages
        run: bash reference/gen.sh --no-build

      - name: Resolve version
        id: ver
        run: |
          # Pilot: use the package version. Production: derive from the v* tag,
          # e.g. VERSION="${GITHUB_REF_NAME#v}".
          VERSION=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
          echo "version=$VERSION" >> "$GITHUB_OUTPUT"

      - name: Deploy with mike (versioned) to gh-pages
        run: |
          mike deploy --config-file reference/mkdocs.yml --push --update-aliases \
            "${{ steps.ver.outputs.version }}" latest
          mike set-default --config-file reference/mkdocs.yml --push latest