Skip to content

Commit 40bf948

Browse files
MattSturgeonMattSturgeon
committed
ci/docs: extract action & refactor workflow
Extract the "build" part of building & deploying the docs website into a `build-docs` composite action. Refactor the workflow to use a matrix job strategy; allowing each branch to be built in parallel and in isolation. In a subsequent job, we combine the builds into a single artifact.
1 parent 91ecff3 commit 40bf948

File tree

2 files changed

+160
-94
lines changed

2 files changed

+160
-94
lines changed

‎.github/actions/build-docs/action.yml

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
name: Build Documentation
2+
description: >
3+
Build Nixvim's documentation and upload an artifact.
4+
5+
Requires having nix installed and Nixvim checked out.
6+
7+
inputs:
8+
sub-path:
9+
description: Move the docs to this sub-directory path.
10+
default: ""
11+
base-href:
12+
description: The base href to use when building the docs.
13+
default: /nixvim/
14+
versions:
15+
description: JSON array describing Nixvim versions to be linked in the docs.
16+
default: "[]"
17+
artifact-name:
18+
description: Artifact name. Set to "" to prevent uploading.
19+
default: docs
20+
retention-days:
21+
description: Days after which artifact will expire.
22+
default: "1"
23+
24+
outputs:
25+
artifact-id:
26+
description: The ID of the artifact that was uploaded.
27+
value: ${{ steps.upload.outputs.artifact-id }}
28+
29+
runs:
30+
using: "composite"
31+
steps:
32+
- name: Create temp directory
33+
id: out-dir
34+
shell: bash
35+
run: |
36+
dir=$(mktemp -d)
37+
{
38+
echo "dir=$dir"
39+
echo "out=$dir/out"
40+
} >> "$GITHUB_OUTPUT"
41+
42+
- name: nix-build
43+
shell: bash
44+
env:
45+
out: ${{ steps.out-dir.outputs.out }}
46+
subPath: ${{ inputs.sub-path }}
47+
baseHref: ${{ inputs.base-href }}
48+
versions: ${{ inputs.versions }}
49+
run: |
50+
nix-build \
51+
--out-link "$out/$subPath" \
52+
--argstr baseHref "$baseHref" \
53+
--argstr versionsJson "$versions" \
54+
--expr '
55+
{
56+
baseHref,
57+
versionsJson,
58+
system ? builtins.currentSystem,
59+
}:
60+
let
61+
# Import flake using flake-compat
62+
flake = import ./.;
63+
inherit (flake.outputs.packages.${system}) docs;
64+
in
65+
docs.override {
66+
inherit baseHref;
67+
availableVersions = builtins.fromJSON versionsJson;
68+
}
69+
'
70+
71+
- name: Upload artifact
72+
id: upload
73+
if: inputs.artifact-name
74+
uses: actions/upload-pages-artifact@v3
75+
with:
76+
path: ${{ steps.out-dir.outputs.out }}
77+
name: ${{ inputs.artifact-name }}
78+
retention-days: ${{ inputs.retention-days }}

‎.github/workflows/website.yml

Lines changed: 82 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -1,140 +1,128 @@
1-
name: Build and deploy documentation
1+
name: Documentation
22

33
on:
44
push:
5-
# Runs on pushes targeting the release branches
65
branches:
76
- main
8-
9-
# Allows you to run this workflow manually from the Actions tab
7+
# Allow running manually
108
workflow_dispatch:
119

12-
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
13-
permissions:
14-
contents: read
15-
pages: write
16-
id-token: write
17-
1810
# Allow one concurrent deployment
1911
concurrency:
20-
group: "pages"
12+
group: docs-website
2113
cancel-in-progress: true
2214

2315
jobs:
24-
deploy:
25-
if: github.repository == 'nix-community/nixvim'
26-
environment:
27-
name: github-pages
28-
url: ${{ steps.deployment.outputs.page_url }}
16+
build:
17+
name: Build ${{ matrix.name }}
2918
runs-on: ubuntu-latest
30-
timeout-minutes: 40
3119

32-
env:
33-
repo: ${{ github.repository }}
34-
repoName: ${{ github.event.repository.name }}
35-
out: docs-build
20+
strategy:
21+
fail-fast: true
22+
matrix:
23+
# TODO: generate matrix from version-info.toml
24+
include:
25+
- name: unstable
26+
ref: main
27+
sub-path: ""
28+
base-href: /nixvim/
29+
- name: "25.05"
30+
ref: nixos-25.05
31+
sub-path: "25.05"
32+
base-href: /nixvim/25.05/
33+
- name: "24.11"
34+
ref: nixos-24.11
35+
sub-path: "24.11"
36+
base-href: /nixvim/24.11/
3637

3738
steps:
3839
- name: Install nix
3940
uses: cachix/install-nix-action@v31
40-
with:
41-
nix_path: nixpkgs=channel:nixos-unstable
4241

4342
- name: Configure cachix
4443
uses: cachix/cachix-action@v16
4544
with:
4645
name: nix-community
47-
authToken: "${{ secrets.CACHIX_AUTH_TOKEN }}"
46+
authToken: ${{ secrets.CACHIX_AUTH_TOKEN }}
4847

49-
- name: Build docs
50-
run: |
51-
set -ex
48+
- name: Checkout
49+
uses: actions/checkout@v4
50+
with:
51+
ref: ${{ inputs.ref }}
5252

53-
# A list of all doc versions to be built,
54-
# (Written to versions.json)
55-
echo '
53+
# Uses the build-docs action from the checked-out nixvim branch
54+
- name: Build docs
55+
uses: ./.github/actions/build-docs
56+
with:
57+
artifact-name: ${{ matrix.name }}-docs
58+
sub-path: ${{ matrix.sub-path }}
59+
base-href: ${{ matrix.base-href }}
60+
# TODO: generate JSON from version-info.toml
61+
versions: >
5662
[
5763
{
5864
"branch": "main",
59-
"nixpkgsBranch": "nixos-unstable"
65+
"nixpkgsBranch": "nixos-unstable",
66+
"baseHref": "/nixvim/"
6067
},
6168
{
6269
"branch": "nixos-25.05",
6370
"nixpkgsBranch": "nixos-25.05",
64-
"subPath": "25.05"
71+
"baseHref": "/nixvim/25.05/"
6572
},
6673
{
6774
"branch": "nixos-24.11",
6875
"nixpkgsBranch": "nixos-24.11",
69-
"subPath": "24.11"
76+
"baseHref": "/nixvim/24.11/"
7077
}
7178
]
72-
' | jq \
73-
--arg repoName "$repoName" \
74-
'map(
75-
.
76-
# Ensure subPath is a string
77-
| .subPath = (.subPath // "")
78-
# Construct baseHref from $repoName and .subPath
79-
| .baseHref = (
80-
.subPath
81-
| if . == "" then "" else "/\(.)" end
82-
| $repoName + .
83-
| "/\(.)/"
84-
)
85-
)' > versions.json
86-
87-
# 1: branch
88-
# 2: baseHref
89-
# 3: install dir
90-
build() {
91-
flakeref="github:${repo}${1:+/$1}"
92-
baseHref="$2"
93-
installDir="${out}${3:+/$3}"
94-
95-
# Build docs for the given flake ref, overriding the relevant derivation args
96-
nix build --impure \
97-
--argstr flakeref "$flakeref" \
98-
--argstr baseHref "$baseHref" \
99-
--arg-from-file versionsJson versions.json \
100-
--expr '
101-
{
102-
flakeref,
103-
baseHref,
104-
versionsJson,
105-
system ? builtins.currentSystem,
106-
}:
107-
let
108-
flake = builtins.getFlake flakeref;
109-
packages = flake.outputs.packages.${system};
110-
in
111-
packages.docs.override {
112-
inherit baseHref;
113-
availableVersions = builtins.fromJSON versionsJson;
114-
}
115-
'
116-
117-
# Copy the result to the install dir
118-
mkdir -p "$installDir"
119-
cp -r result/* "$installDir"
120-
}
121-
122-
# For each version of the docs...
123-
jq -c '.[]' versions.json |
124-
while IFS=$"\n" read -r entry; do
125-
branch=$(echo "$entry" | jq -r '.branch')
126-
baseHref=$(echo "$entry" | jq -r '.baseHref')
127-
installDir=$(echo "$entry" | jq -r '.subPath')
128-
129-
# Build this version of the docs
130-
build "$branch" "$baseHref" "$installDir"
131-
done
79+
80+
combine:
81+
name: Combine builds
82+
runs-on: ubuntu-latest
83+
needs: build
84+
85+
env:
86+
in: artifacts
87+
out: combined
88+
89+
steps:
90+
- name: Download artifacts
91+
uses: actions/download-artifact@v4
92+
with:
93+
path: ${{ env.in }}
94+
pattern: "*-docs"
95+
merge-multiple: false
96+
97+
- name: Extract archives
98+
run: |
99+
mkdir -p "$out"
100+
find "$in" -name artifact.tar \
101+
| parallel tar \
102+
--verbose \
103+
--extract \
104+
--file {} \
105+
--directory "$out"
132106
133107
- name: Upload artifact
134108
uses: actions/upload-pages-artifact@v3
135109
with:
136-
path: "docs-build"
110+
path: ${{ env.out }}
137111

112+
deploy:
113+
name: Deploy
114+
runs-on: ubuntu-latest
115+
needs: combine
116+
117+
permissions:
118+
pages: write # to deploy to Pages
119+
id-token: write # to verify the deployment originates from an appropriate source
120+
121+
environment:
122+
name: github-pages
123+
url: ${{ steps.deployment.outputs.page_url }}
124+
125+
steps:
138126
- name: Deploy to GitHub Pages
139127
id: deployment
140128
uses: actions/deploy-pages@v4

0 commit comments

Comments
 (0)