Repository navigation
242 lines (218 loc) · 10.2 KB
/
Copy pathdocs.yml
File metadata and controls
242 lines (218 loc) · 10.2 KB
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
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
name: docs
# Every documentation version is a separate Hugo build, published under
# https://go-embedded-ruby.github.io/docs/<version>/ on the gh-pages branch, where <version> is
# the minor version of the code the pages describe (params.docs.version in
# hugo.yaml: v0.3.1 -> 0.3), or "main" while no release is tagged. Each push to
# main replaces that version's path and leaves the others alone. Pull requests
# build and check, and publish nothing.
#
# ⛔ This replaced MkDocs Material plus mike: a Python toolchain, a
# requirements.txt and a pip install to render a static site for a pure-Go
# organisation.
on:
push:
branches: [main]
pull_request:
workflow_dispatch:
permissions:
contents: read
env:
HUGO_VERSION: "0.167.0"
# sha256 of hugo_${HUGO_VERSION}_linux-amd64.tar.gz, from the release's checksums.txt.
HUGO_SHA256: "4d84519b9f619e6d4c3fb45a50157abeabeb724f859c60605f44c23def6e1169"
DOCS_URL: "https://go-embedded-ruby.github.io/docs"
jobs:
build:
runs-on: ubuntu-latest
outputs:
version: ${{ steps.version.outputs.version }}
steps:
- name: Checkout
uses: actions/checkout@v7
with:
# themes/hextra is the tannevaled/hextra fork, pinned to a release tag.
submodules: recursive
# The whole history: each page's date comes from git.
fetch-depth: 0
- name: Install Hugo ${{ env.HUGO_VERSION }}
run: |
curl -fsSL -o /tmp/hugo.tar.gz \
"https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
echo "${HUGO_SHA256} /tmp/hugo.tar.gz" | sha256sum -c -
sudo tar -xzf /tmp/hugo.tar.gz -C /usr/local/bin hugo
hugo version
- name: Version
id: version
run: |
documented=$(hugo config --format json | jq -r '.params.docs.version')
if [ "${documented}" = main ]; then
version=main
else
version=$(printf '%s\n' "${documented}" | sed -nE 's/^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/\1.\2/p')
fi
if [ -z "${version}" ]; then
echo "::error::params.docs.version in hugo.yaml is \"${documented}\", not vMAJOR.MINOR.PATCH or main"
exit 1
fi
echo "version=${version}" >> "$GITHUB_OUTPUT"
echo "documented ${documented}: documentation version ${version}"
# --panicOnWarning: a relref to a page that is not there, a deprecated
# setting or a template warning fails the build rather than scrolling by.
- name: Build
env:
HUGO_ENVIRONMENT: production
run: >-
hugo --gc --minify --panicOnWarning --printPathWarnings
--baseURL "${DOCS_URL}/${{ steps.version.outputs.version }}/"
# ⛔ THE TWO DOCUMENTATION GUARDS. Both existed before the move from
# MkDocs to Hugo (#28), which rewrote this file and dropped them: they
# stayed in tools/ and nothing called them, so for two releases the pages
# could have stated any conformance total and any example output without
# a build disagreeing. tools/wired is the test that now fails when a tool
# under tools/ is named by no workflow, because a guard that is not wired
# is indistinguishable from one that passes -- both are silent.
#
# They run in `build`, which also covers pull requests, so a wrong figure
# blocks the change rather than being found after publication.
- uses: actions/setup-go@v6
with:
go-version: '1.27.3'
- name: Every tool under tools/ is called by a workflow
run: go test ./...
- name: The stated conformance totals match the gate
run: go run ./tools/conformancefigure --root content/en
# The examples carry their answers in `# =>` comments; this runs them.
# rbgo is built from the ruby repository's main so they are judged against
# the interpreter these pages describe. An interpreter that cannot be
# produced exits 2 -- a REFUSAL, not a pass.
- name: The Ruby examples print what the pages say they print
run: |
# GOBIN names the destination: `go install` otherwise writes to
# $(go env GOPATH)/bin, and an install that lands elsewhere looks
# exactly like one that worked.
GOBIN=/tmp go install github.com/go-embedded-ruby/ruby/cmd/rbgo@main
go run ./tools/docexample --rbgo /tmp/rbgo --root content/en
# docexample judges the examples that claim an answer -- 11 of them. The
# scientific-stack page also PRINTS around 150 method names in prose, and
# nothing read those until this step: it asks the same interpreter whether
# each one is a method it really answers, and compares the counts the page
# states with the counts the modules have.
#
# It uses the /tmp/rbgo the step above installed. If that step ever goes
# away this one exits 2 -- a refusal, not a pass -- which is the failure
# worth having. Its own extraction is covered by `go test ./...` above,
# which is why it has no -selftest flag of its own.
- name: Every method name the pages print is one the interpreter answers
run: go run ./tools/numericsurface --rbgo /tmp/rbgo --root content/en
# One level up from the method names: each module section also names the
# LIBRARY it binds, and 3 of the 12 were wrong on 2026-10-20 -- each one
# naming a library rbgo had stopped using. rbgo's go.mod is the
# tie-breaker, because a library that is swapped out disappears from it.
#
# ⛔ A SEPARATE step from the one above on purpose. This one fetches over
# the network and that one does not, so a flaky fetch must not be able to
# take the interpreter check down with it -- a run here failed once on
# sum.golang.org dropping an HTTP/2 stream. It exits 2 when it cannot
# read the dependencies, which is a refusal rather than a pass.
- name: Every library a module section links to is one rbgo depends on
run: go run ./tools/upstreamlinks --root content/en
- name: Lay out the site for the link check
run: |
mkdir -p _check/docs
cp -R public "_check/docs/${{ steps.version.outputs.version }}"
- name: Check links
uses: lycheeverse/lychee-action@v2
with:
args: >-
--offline --no-progress --include-fragments
--index-files index.html
--root-dir ${{ github.workspace }}/_check
'_check/docs/**/*.html'
fail: true
- uses: actions/upload-artifact@v7
with:
name: site
path: public
retention-days: 7
deploy:
if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
needs: build
# Never two deploys at once: both would push gh-pages and the second would
# be rejected. cancel-in-progress stays false — killing a publish half way
# through is worse than making it wait.
concurrency:
group: gh-pages-deploy
cancel-in-progress: false
runs-on: ubuntu-latest
permissions:
contents: write
pages: write
steps:
- uses: actions/checkout@v7
with:
path: gh-pages
fetch-depth: 0
- name: Switch to gh-pages
working-directory: gh-pages
run: |
if git ls-remote --exit-code --heads origin gh-pages >/dev/null; then
git fetch -q origin gh-pages
git checkout -q -B gh-pages FETCH_HEAD
else
echo "no gh-pages branch yet: starting one"
git checkout -q --orphan gh-pages
git rm -rqf .
git clean -fdxq
fi
- uses: actions/download-artifact@v8
with:
name: site
path: site
- uses: actions/setup-go@v6
with:
go-version: '1.27.3'
# ⛔ THE VERSION GOES AT THE BRANCH ROOT. This step used to write
# docs/<version>/ — but a project repository named "docs" is ALREADY
# served at /docs/, so the site landed at /docs/docs/<version>/ while
# /docs/latest/ went on serving the MkDocs build mike had left there.
# Both URLs answered 200, which is why the green deploy said nothing.
#
# pagespublish replaces that version and nothing else, writes
# versions.json in mike's format (what the Hextra fork's version selector
# reads), points latest at the newest release, leaves the root
# redirecting to it, and removes the misplaced docs/ directory once.
- name: Publish ${{ needs.build.outputs.version }}
run: >-
go run github.com/go-fleettools/fleettools/cmd/pagespublish@v0.26.0
"${{ needs.build.outputs.version }}" site gh-pages
- name: Push gh-pages
id: push
working-directory: gh-pages
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add -A
if git diff --cached --quiet; then
echo "nothing changed"
exit 0
fi
git commit -q -m "Deployed ${GITHUB_SHA::7} to ${{ needs.build.outputs.version }} with Hugo ${HUGO_VERSION}"
git push origin HEAD:gh-pages
echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
# ⛔ A GREEN PUSH IS NOT A PUBLISHED SITE. GitHub's legacy "pages build and
# deployment" for the gh-pages branch sometimes stalls in updating_pages and
# fails with "Timeout reached, aborting!" after 10 minutes (3 times on
# 2026-11-05/06, runs 42058763350 and 42252993462); re-running it does not
# help and re-running this workflow pushes nothing. pagesbuild waits for a
# build of the pushed commit to be "built", requests a new one when it is
# not, and fails this job if the site is still not built.
- name: Wait for the Pages build
if: steps.push.outputs.sha != ''
env:
GH_TOKEN: ${{ github.token }}
run: |
umask 077
printf '%s' "${GH_TOKEN}" > "${RUNNER_TEMP}/pages-token"
go run github.com/go-fleettools/fleettools/cmd/pagesbuild@v0.80.0 \
--token-file "${RUNNER_TEMP}/pages-token" \
"${GITHUB_REPOSITORY}" "${{ steps.push.outputs.sha }}"