Repository navigation
158 lines (138 loc) · 5.09 KB
/
Copy pathdocs.yml
File metadata and controls
158 lines (138 loc) · 5.09 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
name: Docs
on:
push:
branches: [main]
paths:
- "docs/sphinx/**"
- "docs/README.md"
- "src/unilab/**"
- "scripts/generate_support_matrix.py"
- "src/unilab/conf/**"
- "README.md"
- "CONTRIBUTING.md"
- "AGENTS.md"
- "CLAUDE.md"
- ".github/workflows/docs.yml"
pull_request:
branches: [main]
paths:
- "docs/sphinx/**"
- "docs/README.md"
- "src/unilab/**"
- "scripts/generate_support_matrix.py"
- "src/unilab/conf/**"
- "README.md"
- "CONTRIBUTING.md"
- "AGENTS.md"
- "CLAUDE.md"
- ".github/workflows/docs.yml"
workflow_dispatch:
permissions:
contents: read
concurrency:
group: docs-${{ github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
jobs:
build:
name: Build Sphinx
runs-on: ubuntu-latest
timeout-minutes: 30
env:
UNILAB_DOCS_SKIP_AUTODOC: "1"
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v8.0.0
with:
python-version: "3.11"
- name: Build prose-only HTML
working-directory: docs/sphinx
run: >
uv run --no-project
--with-requirements requirements.txt
sphinx-build -b html -n source build/html
- name: Upload built site
uses: actions/upload-artifact@v4
with:
name: docs-html
path: docs/sphinx/build/html
retention-days: 7
deploy:
name: Deploy to UniLab-doc gh-pages
needs: build
if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
runs-on: ubuntu-latest
timeout-minutes: 45
steps:
- name: Checkout
uses: actions/checkout@v4
with:
# sphinx-multiversion needs full git refs to build every
# whitelisted branch/tag.
fetch-depth: 0
- name: Install uv
uses: astral-sh/setup-uv@v8.0.0
with:
python-version: "3.11"
- name: Install system deps
run: |
sudo apt-get update
sudo apt-get install -y --no-install-recommends \
libgl1 libegl1 libosmesa6 libglfw3 \
ffmpeg
- name: Install UniLab (autodoc target)
id: install_unilab
continue-on-error: true
# Full build so api_reference autodoc renders. If the install fails
# we fall back to a prose-only build and still deploy.
run: |
uv sync
uv pip install -r docs/sphinx/requirements.txt
- name: Configure prose-only fallback
if: steps.install_unilab.outcome != 'success'
run: |
echo "::warning::UniLab install failed — deploying prose-only docs"
echo "UNILAB_DOCS_SKIP_AUTODOC=1" >> "$GITHUB_ENV"
- name: Compute release-line tag whitelist
# Publish the x.y.0 release of every minor line (v1.0.0, v1.1.0,
# v1.2.0, ...) alongside main. New minor releases are picked up
# automatically on the next docs deploy.
run: |
whitelist=$(git tag --list 'v1.*.0' | sort -V | paste -sd'|')
echo "Publishing release lines: $whitelist"
echo "SMV_TAG_WHITELIST=^(${whitelist})$" >> "$GITHUB_ENV"
- name: Build full HTML (all whitelisted versions)
working-directory: docs/sphinx
# sphinx-multiversion builds one subdirectory per whitelisted ref
# (main + the release-line tags computed above; see smv_* in
# source/conf.py). The prose-only fallback still applies —
# UNILAB_DOCS_SKIP_AUTODOC is honoured by conf.py inside each
# per-version build.
run: uv run --no-sync sphinx-multiversion source build/html
- name: Add root redirect
working-directory: docs/sphinx
# Versioned builds land in build/html/<version>/; send / to main.
run: echo '<meta http-equiv="refresh" content="0; url=main/en/0-index.html">' > build/html/index.html
- name: Remove Sphinx doctree caches
working-directory: docs/sphinx
run: find build/html -type d -name .doctrees -exec rm -rf {} +
- name: Push to UniLab-doc gh-pages
uses: peaceiris/actions-gh-pages@v4
with:
# SSH deploy key for unilabsim/UniLab-doc (write access required).
# Stored in this repo's Secrets as UNILAB_DOC_DEPLOY_KEY.
deploy_key: ${{ secrets.UNILAB_DOC_DEPLOY_KEY }}
external_repository: unilabsim/UniLab-doc
publish_branch: gh-pages
publish_dir: docs/sphinx/build/html
# Keep files not touched by this deploy: older version directories
# and the pre-existing root-level pages stay reachable, so old
# external links keep working.
keep_files: true
user_name: "github-actions[bot]"
user_email: "github-actions[bot]@users.noreply.github.com"
commit_message: "docs: deploy from UniLab@${{ github.sha }}"
full_commit_message: |
docs: deploy from UniLab@${{ github.sha }}
Source: ${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}