Skip to content

Commit 306dc46

Browse files
vdusekclaude
vdusek
and
claude
authored
ci: Extract docs versioning and release into reusable workflows (#1846)
## Summary **Docs versioning** (`manual_version_docs.yaml`): - Extract the inline `version_docs` job from `manual_release_stable.yaml` into a standalone reusable workflow - Can be triggered manually from the GitHub UI (with an optional ref input) or called from the release pipeline - Fix `api:version` ENOENT bug by running docusaurus commands through `uv run` - Clean up all existing versions for the same major version, not just exact major.minor match - Remove non-docs artifacts (pyproject.toml, .gitignore, caches) from versioned doc snapshots **Docs release** (`manual_release_docs.yaml`): - Rename `_release_docs.yaml` to `manual_release_docs.yaml` to match the naming convention - Add optional `ref` input to `workflow_dispatch` so it can be triggered from the GitHub UI with a specific ref (falling back to the default branch) - Replace `CHECKOUT_REF` env var approach with a `Determine checkout ref` step, consistent with `manual_version_docs.yaml` - Update all references in `manual_release_stable.yaml` and `on_master.yaml` --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 1624e20 commit 306dc46

9 files changed

Lines changed: 160 additions & 90 deletions

File tree

.github/workflows/_release_docs.yaml renamed to .github/workflows/manual_release_docs.yaml

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,20 @@
1-
name: Doc release
1+
name: Release docs
22

33
on:
44
# Runs when manually triggered from the GitHub UI.
55
workflow_dispatch:
6+
inputs:
7+
ref:
8+
description: Git ref to checkout (branch, tag, or SHA). Defaults to the default branch.
9+
required: false
10+
type: string
11+
default: ""
612

713
# Runs when invoked by another workflow.
814
workflow_call:
915
inputs:
1016
ref:
17+
description: Git ref to checkout (branch, tag, or SHA)
1118
required: true
1219
type: string
1320

@@ -17,11 +24,10 @@ permissions:
1724
env:
1825
NODE_VERSION: 22
1926
PYTHON_VERSION: 3.14
20-
CHECKOUT_REF: ${{ github.event_name == 'workflow_call' && inputs.ref || github.ref }}
2127

2228
jobs:
2329
release_docs:
24-
name: Doc release
30+
name: Release docs
2531
environment:
2632
name: github-pages
2733
permissions:
@@ -31,11 +37,20 @@ jobs:
3137
runs-on: ubuntu-latest
3238

3339
steps:
40+
- name: Determine checkout ref
41+
id: resolve_ref
42+
env:
43+
INPUT_REF: ${{ inputs.ref }}
44+
DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
45+
run: |
46+
REF="${INPUT_REF:-$DEFAULT_BRANCH}"
47+
echo "ref=$REF" >> "$GITHUB_OUTPUT"
48+
3449
- name: Checkout repository
3550
uses: actions/checkout@v6
3651
with:
3752
token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
38-
ref: ${{ env.CHECKOUT_REF }}
53+
ref: ${{ steps.resolve_ref.outputs.ref }}
3954

4055
- name: Set up Node
4156
uses: actions/setup-node@v6

‎.github/workflows/manual_release_stable.yaml‎

Lines changed: 5 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -107,71 +107,12 @@ jobs:
107107
version_docs:
108108
name: Version docs
109109
needs: [release_prepare, changelog_update, pypi_publish]
110-
runs-on: ubuntu-latest
111-
outputs:
112-
version_docs_commitish: ${{ steps.commit_versioned_docs.outputs.commit_long_sha }}
113110
permissions:
114111
contents: write
115-
env:
116-
NODE_VERSION: 22
117-
PYTHON_VERSION: 3.14
118-
119-
steps:
120-
- name: Checkout repository
121-
uses: actions/checkout@v6
122-
with:
123-
token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
124-
ref: ${{ needs.changelog_update.outputs.changelog_commitish }}
125-
126-
- name: Set up Node
127-
uses: actions/setup-node@v6
128-
with:
129-
node-version: ${{ env.NODE_VERSION }}
130-
131-
- name: Set up Python
132-
uses: actions/setup-python@v6
133-
with:
134-
python-version: ${{ env.PYTHON_VERSION }}
135-
136-
- name: Set up uv package manager
137-
uses: astral-sh/setup-uv@v7
138-
with:
139-
python-version: ${{ env.PYTHON_VERSION }}
140-
141-
- name: Install Python dependencies
142-
run: uv run poe install-dev
143-
144-
- name: Install website dependencies
145-
run: |
146-
cd website
147-
corepack enable
148-
yarn install
149-
150-
- name: Snapshot the current version
151-
run: |
152-
cd website
153-
VERSION="$(python -c "import tomllib, pathlib; print(tomllib.loads(pathlib.Path('../pyproject.toml').read_text())['project']['version'])")"
154-
MAJOR_MINOR="$(echo "$VERSION" | cut -d. -f1-2)"
155-
export MAJOR_MINOR
156-
# Remove existing version if present (patch releases override)
157-
rm -rf "versioned_docs/version-${MAJOR_MINOR}"
158-
rm -rf "versioned_sidebars/version-${MAJOR_MINOR}-sidebars.json"
159-
jq 'map(select(. != env.MAJOR_MINOR))' versions.json > tmp.json && mv tmp.json versions.json
160-
# Build API reference and create version snapshots
161-
bash build_api_reference.sh
162-
npx docusaurus docs:version "$MAJOR_MINOR"
163-
npx docusaurus api:version "$MAJOR_MINOR"
164-
# Changelog is not versioned - it is copied from root at build time
165-
rm -f "versioned_docs/version-${MAJOR_MINOR}/changelog.md"
166-
echo "changelog.md" > "versioned_docs/version-${MAJOR_MINOR}/.gitignore"
167-
168-
- name: Commit and push versioned docs
169-
id: commit_versioned_docs
170-
uses: EndBug/add-and-commit@v10
171-
with:
172-
add: "website/versioned_docs website/versioned_sidebars website/versions.json"
173-
message: "docs: version ${{ needs.release_prepare.outputs.version_number }} docs [skip ci]"
174-
default_author: github_actions
112+
uses: ./.github/workflows/manual_version_docs.yaml
113+
with:
114+
ref: ${{ needs.changelog_update.outputs.changelog_commitish }}
115+
secrets: inherit
175116

176117
doc_release:
177118
name: Doc release
@@ -180,7 +121,7 @@ jobs:
180121
contents: write
181122
pages: write
182123
id-token: write
183-
uses: ./.github/workflows/_release_docs.yaml
124+
uses: ./.github/workflows/manual_release_docs.yaml
184125
with:
185126
# Use the version_docs commit to include both changelog and versioned docs.
186127
ref: ${{ needs.version_docs.outputs.version_docs_commitish }}

‎.github/workflows/manual_version_docs.yaml‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
name: Version docs
2+
3+
on:
4+
# Runs when manually triggered from the GitHub UI.
5+
workflow_dispatch:
6+
inputs:
7+
ref:
8+
description: Git ref to checkout (branch, tag, or SHA). Defaults to the default branch.
9+
required: false
10+
type: string
11+
default: ""
12+
13+
# Runs when invoked by another workflow.
14+
workflow_call:
15+
inputs:
16+
ref:
17+
description: Git ref to checkout (branch, tag, or SHA)
18+
required: true
19+
type: string
20+
outputs:
21+
version_docs_commitish:
22+
description: The commit SHA of the versioned docs commit
23+
value: ${{ jobs.version_docs.outputs.version_docs_commitish }}
24+
25+
concurrency:
26+
group: version-docs
27+
cancel-in-progress: false
28+
29+
permissions:
30+
contents: read
31+
32+
env:
33+
NODE_VERSION: "22"
34+
PYTHON_VERSION: "3.14"
35+
36+
jobs:
37+
version_docs:
38+
name: Version docs
39+
runs-on: ubuntu-latest
40+
outputs:
41+
version_docs_commitish: ${{ steps.resolve_commitish.outputs.commitish }}
42+
permissions:
43+
contents: write
44+
45+
steps:
46+
- name: Determine checkout ref
47+
id: resolve_ref
48+
env:
49+
INPUT_REF: ${{ inputs.ref }}
50+
DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
51+
run: |
52+
REF="${INPUT_REF:-$DEFAULT_BRANCH}"
53+
echo "ref=$REF" >> "$GITHUB_OUTPUT"
54+
55+
- name: Checkout repository
56+
uses: actions/checkout@v6
57+
with:
58+
token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
59+
ref: ${{ steps.resolve_ref.outputs.ref }}
60+
61+
- name: Set up Node
62+
uses: actions/setup-node@v6
63+
with:
64+
node-version: ${{ env.NODE_VERSION }}
65+
66+
- name: Set up Python
67+
uses: actions/setup-python@v6
68+
with:
69+
python-version: ${{ env.PYTHON_VERSION }}
70+
71+
- name: Set up uv package manager
72+
uses: astral-sh/setup-uv@v7
73+
with:
74+
python-version: ${{ env.PYTHON_VERSION }}
75+
76+
- name: Install Python dependencies
77+
run: uv run poe install-dev
78+
79+
- name: Snapshot the current version
80+
id: snapshot
81+
run: |
82+
cd website
83+
corepack enable
84+
yarn install
85+
86+
# Extract version from pyproject.toml.
87+
FULL_VERSION="$(uv version --short)"
88+
MAJOR_MINOR_VERSION="$(echo "$FULL_VERSION" | cut -d. -f1-2)"
89+
MAJOR_VERSION="$(echo "$FULL_VERSION" | cut -d. -f1)"
90+
echo "version=$FULL_VERSION" >> "$GITHUB_OUTPUT"
91+
echo "Version: $FULL_VERSION, Major.Minor: $MAJOR_MINOR_VERSION, Major: $MAJOR_VERSION"
92+
93+
# Find the existing versions for this major in versions.json (if any).
94+
if [[ -f versions.json ]]; then
95+
OLD_VERSIONS="$(jq -r --arg major "$MAJOR_VERSION" '.[] | select(startswith($major + "."))' versions.json)"
96+
else
97+
OLD_VERSIONS=""
98+
echo "[]" > versions.json
99+
fi
100+
101+
# Remove all old versions for this major (if found).
102+
if [[ -n "$OLD_VERSIONS" ]]; then
103+
while IFS= read -r OLD_VERSION; do
104+
[[ -z "$OLD_VERSION" ]] && continue
105+
echo "Removing old version $OLD_VERSION for major $MAJOR_VERSION"
106+
rm -rf "versioned_docs/version-${OLD_VERSION}"
107+
rm -f "versioned_sidebars/version-${OLD_VERSION}-sidebars.json"
108+
done <<< "$OLD_VERSIONS"
109+
jq --arg major "$MAJOR_VERSION" 'map(select(startswith($major + ".") | not))' versions.json > tmp.json && mv tmp.json versions.json
110+
else
111+
echo "No existing versions found for major $MAJOR_VERSION, nothing to remove"
112+
fi
113+
114+
# Build API reference and create Docusaurus version snapshots.
115+
bash build_api_reference.sh
116+
uv run npx docusaurus docs:version "$MAJOR_MINOR_VERSION"
117+
uv run npx docusaurus api:version "$MAJOR_MINOR_VERSION"
118+
119+
- name: Commit and push versioned docs
120+
id: commit_versioned_docs
121+
uses: EndBug/add-and-commit@v10
122+
with:
123+
add: website/versioned_docs website/versioned_sidebars website/versions.json
124+
message: "docs: Version docs for v${{ steps.snapshot.outputs.version }} [skip ci]"
125+
default_author: github_actions
126+
127+
- name: Resolve output commitish
128+
id: resolve_commitish
129+
env:
130+
COMMIT_SHA: ${{ steps.commit_versioned_docs.outputs.commit_long_sha }}
131+
run: |
132+
echo "commitish=${COMMIT_SHA:-$(git rev-parse HEAD)}" >> "$GITHUB_OUTPUT"

‎.github/workflows/on_master.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ jobs:
2828
contents: write
2929
pages: write
3030
id-token: write
31-
uses: ./.github/workflows/_release_docs.yaml
31+
uses: ./.github/workflows/manual_release_docs.yaml
3232
with:
3333
# Use the same ref as the one that triggered the workflow.
3434
ref: ${{ github.ref }}
@@ -108,7 +108,7 @@ jobs:
108108
contents: write
109109
pages: write
110110
id-token: write
111-
uses: ./.github/workflows/_release_docs.yaml
111+
uses: ./.github/workflows/manual_release_docs.yaml
112112
with:
113113
# Use the ref from the changelog update to include the updated changelog.
114114
ref: ${{ needs.changelog_update.outputs.changelog_commitish }}

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,8 @@ Session.vim
6363

6464
# Docs
6565
docs/changelog.md
66+
website/versioned_docs/*/changelog.md
67+
website/versioned_docs/*/pyproject.toml
6668

6769
# Website build artifacts, node dependencies
6870
website/build

‎website/versioned_docs/version-0.6/.gitignore‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎website/versioned_docs/version-0.6/pyproject.toml‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎website/versioned_docs/version-1.6/.gitignore‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎website/versioned_docs/version-1.6/pyproject.toml‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

0 commit comments

Comments
 (0)