Skip to content

Commit da68e15

Browse files
jorisdraljorisdral
committed
Split out a GHA workflow file for documentation jobs
Due to the machinations of `cabal haddock-project`, caching has to be done differently when we build the dev haddocks compared to when we build and test the project. It seems simpler to put documentation jobs in their own workflow and update the caching approach there, though that does mean there is some duplication between the documentation workflow and the build-and-test workflow.
1 parent daf3619 commit da68e15

File tree

3 files changed

+135
-69
lines changed

3 files changed

+135
-69
lines changed

‎.github/workflows/check-release-builds.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: Check release builds
1+
name: CI - Check release builds
22

33
on:
44
push:

‎.github/workflows/ci.yml‎

Lines changed: 6 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -53,9 +53,6 @@ jobs:
5353
echo 'matrix.cabal-version: ${{ matrix.os || env.DEFAULT_CABAL_VERSION }}'
5454
echo 'matrix.cabal-flags: ${{ matrix.cabal-flags }}'
5555
echo 'matrix.cabal-project-file: ${{ matrix.cabal-project-file || env.DEFAULT_CABAL_PROJECT_FILE }}'
56-
echo 'matrix.cabal-skip-tests: ${{ matrix.cabal-skip-tests || false }}'
57-
echo 'matrix.cabal-skip-benchmarks: ${{ matrix.cabal-skip-benchmarks || false}}'
58-
echo 'matrix.cabal-documentation: ${{ matrix.cabal-documentation || false }}'
5956
echo 'toJSON(matrix): ${{ toJSON(matrix) }}'
6057
6158
- name: 🗄️ Print CPU info
@@ -78,9 +75,9 @@ jobs:
7875
run: |
7976
cabal configure \
8077
--project-file="${{ matrix.cabal-project-file || env.DEFAULT_CABAL_PROJECT_FILE }}" \
81-
${{ matrix.cabal-skip-tests && '--disable-tests' || '--enable-tests' }} \
82-
${{ matrix.cabal-skip-benchmarks && '--disable-benchmarks' || '--enable-benchmarks' }} \
83-
${{ matrix.cabal-documentation && '--enable-documentation' || '--disable-documentation' }} \
78+
--enable-tests \
79+
--enable-benchmarks \
80+
--disable-documentation \
8481
--ghc-options="-Werror" \
8582
--flag="${{ matrix.cabal-flags }}"
8683
cat "${{ matrix.cabal-project-file || env.DEFAULT_CABAL_PROJECT_FILE }}.local"
@@ -116,14 +113,12 @@ jobs:
116113
key: ${{ steps.cache-cabal.outputs.cache-primary-key }}
117114

118115
- name: 🏗️ Build
119-
if: ${{ !matrix.cabal-skip-tests }}
120116
run: |
121117
cabal build all \
122118
--project-file="${{ matrix.cabal-project-file || env.DEFAULT_CABAL_PROJECT_FILE }}"
123119
124120
- name: 🧪 Test
125121
id: test
126-
if: ${{ !matrix.cabal-skip-tests }}
127122
run: |
128123
cabal test all \
129124
-j1 \
@@ -137,7 +132,7 @@ jobs:
137132
# directory containing the golden files after running the goldens tests
138133
# allows us to diff the expected and actual golden file contents.
139134
- name: 📦 Upload golden files
140-
if: ${{ !matrix.cabal-skip-tests && steps.test.outcome != 'success' && always() }}
135+
if: ${{ steps.test.outcome != 'success' && always() }}
141136
uses: actions/upload-artifact@v4
142137
with:
143138
name: golden-files-${{ runner.os }}-ghc-${{ steps.setup-haskell.outputs.ghc-version }}-cabal-${{ steps.setup-haskell.outputs.cabal-version }}-plan-${{ hashFiles('dist-newstyle/cache/plan.json') }}
@@ -146,28 +141,15 @@ jobs:
146141
retention-days: 1
147142

148143
- name: 🛠️ Setup cabal-docspec (Linux)
149-
if: ${{ !matrix.cabal-skip-tests && runner.os == 'Linux' }}
144+
if: ${{ runner.os == 'Linux' }}
150145
uses: ./.github/actions/setup-cabal-docspec
151146

152147
- name: 🧪 Test with cabal-docspec (Linux)
153-
if: ${{ !matrix.cabal-skip-tests && runner.os == 'Linux' }}
148+
if: ${{ runner.os == 'Linux' }}
154149
run: ./scripts/test-cabal-docspec.sh
155150
env:
156151
SKIP_CABAL_BUILD: true
157152

158-
- name: 🏗️ Build documentation
159-
if: ${{ matrix.cabal-documentation }}
160-
run: ./scripts/generate-haddock.sh
161-
162-
- name: 📦 Upload documentation
163-
if: ${{ matrix.cabal-documentation }}
164-
uses: actions/upload-artifact@v4
165-
with:
166-
name: haddocks-${{ runner.os }}-ghc-${{ matrix.ghc-version || env.DEFAULT_GHC_VERSION }}-cabal-${{ matrix.cabal-version || env.DEFAULT_CABAL_VERSION }}
167-
path: haddocks
168-
if-no-files-found: error
169-
retention-days: 1
170-
171153
strategy:
172154
fail-fast: false
173155
matrix:
@@ -178,7 +160,6 @@ jobs:
178160
# entry under include that assigns these keys creates a new matrix entry
179161
cabal-flags: [""]
180162
cabal-project-file: [""]
181-
cabal-documentation: [false]
182163

183164
include:
184165
# Include builds for various special cases
@@ -188,12 +169,6 @@ jobs:
188169
- name: "Build with cabal.project.release"
189170
os: "ubuntu-latest"
190171
cabal-project-file: "cabal.project.release"
191-
# Include build for documentation
192-
- name: "Build documentation"
193-
os: "ubuntu-latest"
194-
cabal-skip-tests: true
195-
cabal-skip-benchmarks: true
196-
cabal-documentation: true
197172

198173
################################################################################
199174
# Lint with actionlint
@@ -352,40 +327,3 @@ jobs:
352327

353328
- name: 🎗️ Lint with ShellCheck
354329
run: ./scripts/lint-shellcheck.sh
355-
356-
################################################################################
357-
# Publish documentation
358-
################################################################################
359-
publish-documentation:
360-
name: Publish documentation
361-
runs-on: ubuntu-latest
362-
if: ${{ github.event_name == 'push' }}
363-
needs: [build]
364-
365-
permissions:
366-
pages: write
367-
id-token: write
368-
369-
environment:
370-
name: github-pages
371-
url: ${{ steps.publish-pages.outputs.page_url }}
372-
373-
steps:
374-
- name: 🛠️ Setup Pages
375-
uses: actions/configure-pages@v5
376-
377-
- name: 📦 Download documentation
378-
uses: actions/download-artifact@v4
379-
with:
380-
# Ensure that the job that builds the documentation uses the default GHC and Cabal versions.
381-
name: haddocks-Linux-ghc-${{ env.DEFAULT_GHC_VERSION }}-cabal-${{ env.DEFAULT_CABAL_VERSION }}
382-
path: haddocks
383-
384-
- name: 📦 Upload documentation to Pages
385-
uses: actions/upload-pages-artifact@v3
386-
with:
387-
path: haddocks
388-
389-
- name: 🚀 Publish documentation to Pages
390-
id: publish-pages
391-
uses: actions/deploy-pages@v4

‎.github/workflows/documentation.yml‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
name: CI - Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- "main"
7+
pull_request:
8+
merge_group:
9+
10+
concurrency:
11+
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
12+
cancel-in-progress: true
13+
14+
permissions:
15+
contents: read
16+
17+
# Set the default shell on all platforms.
18+
defaults:
19+
run:
20+
shell: sh
21+
22+
env:
23+
ghc-version: "9.6"
24+
cabal-version: "3.12"
25+
cabal-project-file: "cabal.project.debug"
26+
27+
jobs:
28+
################################################################################
29+
# Build documentation
30+
################################################################################
31+
build:
32+
name: Build documentation
33+
runs-on: ubuntu-latest
34+
timeout-minutes: 60
35+
36+
steps:
37+
- name: 📥 Checkout repository
38+
uses: actions/checkout@v4
39+
40+
- name: 🛠️ Setup Haskell
41+
id: setup-haskell
42+
uses: haskell-actions/setup@v2
43+
with:
44+
ghc-version: ${{ env.ghc-version }}
45+
cabal-version: ${{ env.cabal-version }}
46+
47+
- name: 🛠️ Setup system dependencies (Linux)
48+
if: ${{ runner.os == 'Linux' }}
49+
run: sudo apt-get update && sudo apt-get -y install liburing-dev librocksdb-dev
50+
env:
51+
DEBIAN_FRONTEND: "noninteractive"
52+
53+
- name: 🛠️ Configure
54+
run: |
55+
cabal configure \
56+
--project-file="${{ env.cabal-project-file }}" \
57+
--enable-tests \
58+
--enable-benchmarks \
59+
--enable-documentation \
60+
--ghc-options="-Werror"
61+
cat "${{ env.cabal-project-file }}.local"
62+
63+
- name: 💾 Generate Cabal plan
64+
run: |
65+
cabal build all \
66+
--project-file="${{ env.cabal-project-file }}" \
67+
--dry-run
68+
69+
# Use the cache action instead of the restore/save actions, because cabal
70+
# haddock-project (used in the generate-haddock.sh script) tends to
71+
# rebuild dependencies regardless of whether we build the dependencies
72+
# manually beforehand.
73+
- name: 💾 Cache Cabal dependencies
74+
uses: actions/cache@v4
75+
if: ${{ !env.ACT }}
76+
env:
77+
key: build-documentation-${{ runner.os }}-ghc-${{ steps.setup-haskell.outputs.ghc-version }}-cabal-${{ steps.setup-haskell.outputs.cabal-version }}
78+
with:
79+
path: ${{ steps.setup-haskell.outputs.cabal-store }}
80+
key: ${{ env.key }}-plan-${{ hashFiles('dist-newstyle/cache/plan.json') }}
81+
restore-keys: ${{ env.key }}-
82+
83+
- name: 🏗️ Build documentation
84+
run: ./scripts/generate-haddock.sh
85+
86+
- name: 📦 Upload documentation
87+
uses: actions/upload-artifact@v4
88+
with:
89+
name: haddocks-${{ runner.os }}-ghc-${{ env.ghc-version }}-cabal-${{ env.cabal-version }}
90+
path: haddocks
91+
if-no-files-found: error
92+
retention-days: 1
93+
94+
################################################################################
95+
# Publish documentation
96+
################################################################################
97+
publish-documentation:
98+
name: Publish documentation
99+
runs-on: ubuntu-latest
100+
if: ${{ github.event_name == 'push' }}
101+
needs: [build]
102+
103+
permissions:
104+
pages: write
105+
id-token: write
106+
107+
environment:
108+
name: github-pages
109+
url: ${{ steps.publish-pages.outputs.page_url }}
110+
111+
steps:
112+
- name: 🛠️ Setup Pages
113+
uses: actions/configure-pages@v5
114+
115+
- name: 📦 Download documentation
116+
uses: actions/download-artifact@v4
117+
with:
118+
name: haddocks-${{ runner.os }}-ghc-${{ env.ghc-version }}-cabal-${{ env.cabal-version }}
119+
path: haddocks
120+
121+
- name: 📦 Upload documentation to Pages
122+
uses: actions/upload-pages-artifact@v3
123+
with:
124+
path: haddocks
125+
126+
- name: 🚀 Publish documentation to Pages
127+
id: publish-pages
128+
uses: actions/deploy-pages@v4

0 commit comments

Comments
 (0)