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
name: Docs
on:
push:
branches:
pull_request:
workflow_dispatch:
# Required for the Pages deployment to obtain its OIDC token.
permissions:
contents: read
pages: write
id-token: write
concurrency:
# Keyed by ref: the Pages deployment must still serialise on `main`,
# but a pull request must not share a queue with it. A shared group
# let unrelated runs cancel a pull request's `Build rustdoc`, and a
# cancelled run never satisfies a required status check — so the
# pull request could not be merged.
group: pages-${{ github.ref }}
cancel-in-progress: false
jobs:
build:
name: Build rustdoc
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: Install Rust (stable)
uses: dtolnay/rust-toolchain@stable
- uses: Swatinem/rust-cache@v2
- name: Build documentation
env:
# Fail the build on any rustdoc warning (broken intra-doc link,
# missing docs on a public item, etc.).
RUSTDOCFLAGS: "--cfg docsrs --deny warnings"
run: cargo doc --no-deps --all-features
# crates.io serves index.html via metadata_gen/index.html; redirect / to it.
- name: Add root redirect
run: |
set -euo pipefail
cat > target/doc/index.html <<'EOF'
<!doctype html>
<meta charset="utf-8">
<title>metadata-gen documentation</title>
<meta http-equiv="refresh" content="0; url=metadata_gen/index.html">
<link rel="canonical" href="metadata_gen/index.html">
<p>If you are not redirected, <a href="metadata_gen/index.html">open the docs</a>.</p>
EOF
# Custom-domain support: keep the apex CNAME alongside the artifact.
- name: Write CNAME
run: echo "doc.metadata-gen.com" > target/doc/CNAME
- name: Upload Pages artifact
if: github.ref == 'refs/heads/main'
uses: actions/upload-pages-artifact@v5
with:
path: target/doc
deploy:
name: Deploy to GitHub Pages
if: github.ref == 'refs/heads/main'
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy
id: deployment
uses: actions/deploy-pages@v5
# Courtesy probe, not a gate. actions/deploy-pages above is the
# authoritative signal that publishing succeeded; this only confirms
# the custom domain is serving the new content.
#
# It used to fail the job after 5 minutes of HTTP 403. That is what
# GitHub Pages returns while a custom domain's TLS certificate is
# still being provisioned, which routinely takes longer than five
# minutes and is outside this repository's control -- the docs were
# reachable shortly afterwards every time. Failing the deploy job on
# CDN warm-up made a green publish look broken.
#
# The window is now 10 minutes, and a timeout is a warning rather
# than a failure. A genuinely broken publish still shows up as a
# failed Deploy step.
- name: Smoke-check published URL
run: |
set -euo pipefail
URL="https://doc.metadata-gen.com/metadata_gen/"
for i in $(seq 1 20); do
code=$(curl -sS -o /dev/null -w "%{http_code}" "$URL" || true)
echo " attempt $i: HTTP $code"
if [ "$code" = "200" ]; then
echo "✓ docs reachable at $URL"
exit 0
fi
sleep 30
done
echo "::warning::${URL} still returned HTTP ${code} after 10 minutes."
echo "Deployment itself succeeded; this is usually TLS provisioning"
echo "for the custom domain. Check the page manually if it persists."