Skip to content

Commit f4d0c7d

Browse files
hongjr03hongjr03
authored
docs,ci: first stage user guide polish (#148)
1 parent 6d130d9 commit f4d0c7d

88 files changed

Lines changed: 4932 additions & 5766 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/deploy-docs.yml‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
name: Deploy docs to Aliyun OSS
2+
3+
on:
4+
workflow_run:
5+
workflows: ["Build docs"]
6+
types: [completed]
7+
workflow_dispatch:
8+
release:
9+
types: [published]
10+
pull_request_target:
11+
types: [closed]
12+
13+
permissions:
14+
actions: read
15+
contents: read
16+
issues: write
17+
18+
concurrency:
19+
group: docs-deploy
20+
cancel-in-progress: false
21+
22+
env:
23+
ASTRO_SITE: https://vide.pascal-lab.net
24+
25+
jobs:
26+
deploy-preview:
27+
name: Deploy PR preview
28+
if: >
29+
github.event_name == 'workflow_run' &&
30+
github.event.workflow_run.event == 'pull_request' &&
31+
github.event.workflow_run.conclusion == 'success' &&
32+
vars.ENABLE_DOCS_DEPLOY == 'true'
33+
runs-on: ubuntu-latest
34+
steps:
35+
- name: Resolve preview target
36+
id: preview
37+
run: |
38+
set -euo pipefail
39+
40+
pr_number="$(jq -r '.workflow_run.pull_requests[0].number // empty' "${GITHUB_EVENT_PATH}")"
41+
if ! [[ "${pr_number}" =~ ^[0-9]+$ ]]; then
42+
echo "No pull request number found for workflow run ${GITHUB_RUN_ID}."
43+
exit 1
44+
fi
45+
46+
preview_path="preview/pr-${pr_number}/"
47+
preview_url="https://vide.pascal-lab.net/${preview_path}"
48+
49+
echo "pr_number=${pr_number}" >> "${GITHUB_OUTPUT}"
50+
echo "path=${preview_path}" >> "${GITHUB_OUTPUT}"
51+
echo "url=${preview_url}" >> "${GITHUB_OUTPUT}"
52+
53+
- name: Download preview artifact
54+
uses: actions/download-artifact@v4
55+
with:
56+
name: vide-docs-preview
57+
run-id: ${{ github.event.workflow_run.id }}
58+
github-token: ${{ github.token }}
59+
path: preview-dist
60+
61+
- name: Setup ossutil
62+
uses: manyuanrong/setup-ossutil@v2.0
63+
with:
64+
endpoint: ${{ secrets.endpoint }}
65+
access-key-id: ${{ secrets.accessKeyId }}
66+
access-key-secret: ${{ secrets.accessKeySecret }}
67+
68+
- name: Deploy preview to OSS
69+
env:
70+
OSS_BUCKET_NAME: ${{ secrets.bucketName }}
71+
PREVIEW_PATH: ${{ steps.preview.outputs.path }}
72+
PREVIEW_URL: ${{ steps.preview.outputs.url }}
73+
run: |
74+
set -euo pipefail
75+
76+
if [ -z "${OSS_BUCKET_NAME}" ]; then
77+
echo "OSS bucketName secret is required."
78+
exit 1
79+
fi
80+
81+
case "${PREVIEW_PATH}" in
82+
preview/pr-[0-9]*/) ;;
83+
*)
84+
echo "Invalid preview path: ${PREVIEW_PATH}"
85+
exit 1
86+
;;
87+
esac
88+
89+
target="oss://${OSS_BUCKET_NAME}/${PREVIEW_PATH}"
90+
ossutil rm "${target}" -rf || true
91+
ossutil cp preview-dist "${target}" -rf
92+
93+
echo "Preview deployed to ${PREVIEW_URL}" >> "${GITHUB_STEP_SUMMARY}"
94+
95+
- name: Comment preview URL
96+
uses: actions/github-script@v8
97+
env:
98+
PR_NUMBER: ${{ steps.preview.outputs.pr_number }}
99+
PREVIEW_URL: ${{ steps.preview.outputs.url }}
100+
with:
101+
script: |
102+
const prNumber = Number(process.env.PR_NUMBER);
103+
const previewUrl = process.env.PREVIEW_URL;
104+
const marker = `<!-- vide-docs-preview:${prNumber} -->`;
105+
const body = `${marker}\nDocs preview: ${previewUrl}`;
106+
const { owner, repo } = context.repo;
107+
const comments = await github.paginate(github.rest.issues.listComments, {
108+
owner,
109+
repo,
110+
issue_number: prNumber,
111+
per_page: 100,
112+
});
113+
const existing = comments.find((comment) => comment.body?.includes(marker));
114+
if (existing) {
115+
await github.rest.issues.updateComment({
116+
owner,
117+
repo,
118+
comment_id: existing.id,
119+
body,
120+
});
121+
} else {
122+
await github.rest.issues.createComment({
123+
owner,
124+
repo,
125+
issue_number: prNumber,
126+
body,
127+
});
128+
}
129+
130+
deploy-production:
131+
name: Deploy production docs
132+
if: >
133+
(github.event_name == 'release' && github.event.release.prerelease != true && vars.ENABLE_DOCS_DEPLOY == 'true') ||
134+
(github.event_name == 'workflow_dispatch' && vars.ENABLE_DOCS_DEPLOY == 'true')
135+
runs-on: ubuntu-latest
136+
environment:
137+
name: docs
138+
url: https://vide.pascal-lab.net
139+
env:
140+
ASTRO_BASE: /
141+
steps:
142+
- name: Checkout
143+
uses: actions/checkout@v4
144+
145+
- name: Setup Node
146+
uses: actions/setup-node@v4
147+
with:
148+
node-version: 22
149+
cache: npm
150+
cache-dependency-path: docs/package-lock.json
151+
152+
- name: Install dependencies
153+
run: npm ci
154+
working-directory: docs
155+
156+
- name: Build docs
157+
run: npm run build
158+
working-directory: docs
159+
160+
- name: Setup ossutil
161+
uses: manyuanrong/setup-ossutil@v2.0
162+
with:
163+
endpoint: ${{ secrets.endpoint }}
164+
access-key-id: ${{ secrets.accessKeyId }}
165+
access-key-secret: ${{ secrets.accessKeySecret }}
166+
167+
- name: Deploy production to OSS
168+
env:
169+
OSS_BUCKET_NAME: ${{ secrets.bucketName }}
170+
run: |
171+
set -euo pipefail
172+
173+
if [ -z "${OSS_BUCKET_NAME}" ]; then
174+
echo "OSS bucketName secret is required."
175+
exit 1
176+
fi
177+
178+
for key in _astro pagefind advanced-guide changelog en playground schemas user-guide developer-guide staging 404.html index.html robots.txt sitemap-0.xml sitemap-index.xml; do
179+
ossutil rm "oss://${OSS_BUCKET_NAME}/${key}" -rf || true
180+
done
181+
182+
ossutil cp docs/dist "oss://${OSS_BUCKET_NAME}/" -rf
183+
184+
cleanup-preview:
185+
name: Remove closed PR preview
186+
if: >
187+
github.event_name == 'pull_request_target' &&
188+
github.event.action == 'closed' &&
189+
vars.ENABLE_DOCS_DEPLOY == 'true'
190+
runs-on: ubuntu-latest
191+
steps:
192+
- name: Setup ossutil
193+
uses: manyuanrong/setup-ossutil@v2.0
194+
with:
195+
endpoint: ${{ secrets.endpoint }}
196+
access-key-id: ${{ secrets.accessKeyId }}
197+
access-key-secret: ${{ secrets.accessKeySecret }}
198+
199+
- name: Delete preview from OSS
200+
env:
201+
OSS_BUCKET_NAME: ${{ secrets.bucketName }}
202+
PREVIEW_PATH: preview/pr-${{ github.event.pull_request.number }}/
203+
run: |
204+
set -euo pipefail
205+
206+
if [ -z "${OSS_BUCKET_NAME}" ]; then
207+
echo "OSS bucketName secret is required."
208+
exit 1
209+
fi
210+
211+
ossutil rm "oss://${OSS_BUCKET_NAME}/${PREVIEW_PATH}" -rf || true

‎.github/workflows/docs-preview.yml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
name: Build docs
2+
3+
on:
4+
push:
5+
branches: [master]
6+
paths:
7+
- "docs/**"
8+
- ".github/workflows/docs-preview.yml"
9+
- ".github/workflows/deploy-docs.yml"
10+
pull_request:
11+
types: [opened, synchronize, reopened]
12+
paths:
13+
- "docs/**"
14+
- ".github/workflows/docs-preview.yml"
15+
- ".github/workflows/deploy-docs.yml"
16+
17+
permissions:
18+
contents: read
19+
20+
env:
21+
ASTRO_SITE: https://vide.pascal-lab.net
22+
ASTRO_BASE: ${{ github.event_name == 'pull_request' && format('/preview/pr-{0}/', github.event.pull_request.number) || '/' }}
23+
PREVIEW_URL: ${{ github.event_name == 'pull_request' && format('https://vide.pascal-lab.net/preview/pr-{0}/', github.event.pull_request.number) || '' }}
24+
25+
jobs:
26+
build:
27+
name: Build Starlight
28+
runs-on: ubuntu-latest
29+
steps:
30+
- name: Checkout
31+
uses: actions/checkout@v4
32+
33+
- name: Setup Node
34+
uses: actions/setup-node@v4
35+
with:
36+
node-version: 22
37+
cache: npm
38+
cache-dependency-path: docs/package-lock.json
39+
40+
- name: Install dependencies
41+
run: npm ci
42+
working-directory: docs
43+
44+
- name: Build docs
45+
run: npm run build
46+
working-directory: docs
47+
48+
- name: Add preview summary
49+
if: github.event_name == 'pull_request'
50+
run: |
51+
set -euo pipefail
52+
echo "Docs preview will be deployed to ${PREVIEW_URL}" >> "${GITHUB_STEP_SUMMARY}"
53+
54+
- name: Upload preview artifact
55+
if: github.event_name == 'pull_request'
56+
uses: actions/upload-artifact@v4
57+
with:
58+
name: vide-docs-preview
59+
path: docs/dist
60+
retention-days: 7

‎.github/workflows/docs.yml‎

Lines changed: 0 additions & 55 deletions
This file was deleted.

0 commit comments

Comments
 (0)