Skip to content

Commit ab9ecf0

Browse files
committed
feat: 添加 GitHub Pages 自动部署配置,移除 Jupyter Notebook 引用
- 添加 GitHub Actions 工作流自动部署文档到 GitHub Pages - 创建 docs/requirements.txt 管理文档依赖 - 从 mkdocs.yml 移除 mkdocs-jupyter 插件 - 删除 docs/examples 符号链接,避免包含 .ipynb 文件 - 添加部署总结文档
1 parent f581eda commit ab9ecf0

File tree

5 files changed

+164
-2
lines changed

5 files changed

+164
-2
lines changed

.github/workflows/deploy-docs.yml

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Deploy MkDocs to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- master
8+
workflow_dispatch:
9+
10+
permissions:
11+
contents: write
12+
pages: write
13+
id-token: write
14+
15+
concurrency:
16+
group: "pages"
17+
cancel-in-progress: false
18+
19+
jobs:
20+
deploy:
21+
runs-on: ubuntu-latest
22+
steps:
23+
- name: Checkout
24+
uses: actions/checkout@v4
25+
with:
26+
fetch-depth: 0
27+
28+
- name: Setup Python
29+
uses: actions/setup-python@v5
30+
with:
31+
python-version: '3.11'
32+
cache: 'pip'
33+
34+
- name: Install dependencies
35+
run: |
36+
pip install --upgrade pip
37+
pip install -r docs/requirements.txt
38+
39+
- name: Build MkDocs
40+
run: mkdocs build --clean --strict
41+
42+
- name: Deploy to GitHub Pages
43+
run: |
44+
git config --global user.name "github-actions[bot]"
45+
git config --global user.email "github-actions[bot]@users.noreply.github.com"
46+
mkdocs gh-deploy --force
47+

DEPLOY_SUMMARY.md

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# GitHub Pages 部署配置总结
2+
3+
## ✅ 已完成的配置
4+
5+
### 1. GitHub Actions 工作流
6+
创建了 `.github/workflows/deploy-docs.yml`,实现自动部署功能:
7+
- 当代码推送到 `main``master` 分支时自动触发
8+
- 支持手动触发(workflow_dispatch)
9+
- 自动构建并部署到 GitHub Pages
10+
11+
### 2. 文档依赖管理
12+
创建了 `docs/requirements.txt`,包含所需的依赖:
13+
- mkdocs
14+
- mkdocs-material
15+
- mkdocstrings[python]
16+
- pymdown-extensions
17+
- mkdocs-shadcn
18+
19+
### 3. 清理 Jupyter Notebook 引用
20+
- ✅ 删除了 `docs/examples` 符号链接(之前指向 `../examples`
21+
- ✅ 从 `mkdocs.yml` 移除了 `mkdocs-jupyter` 插件
22+
- ✅ 从 `docs/requirements.txt` 移除了 `mkdocs-jupyter` 依赖
23+
- ✅ 文档构建成功,不再包含 `.ipynb` 文件
24+
25+
## 🚀 部署步骤
26+
27+
### 第一步:配置 GitHub Pages
28+
29+
1. 访问:https://github.com/modelscope/RM-Gallery/settings/pages
30+
2.**Source** 部分选择:
31+
- Source: **Deploy from a branch**
32+
- Branch: **gh-pages** / `/(root)`
33+
3. 点击 **Save**
34+
35+
### 第二步:配置 GitHub Actions 权限
36+
37+
1. 访问:https://github.com/modelscope/RM-Gallery/settings/actions
38+
2.**Workflow permissions** 部分:
39+
- 选择 **Read and write permissions**
40+
- 勾选 **Allow GitHub Actions to create and approve pull requests**
41+
3. 点击 **Save**
42+
43+
### 第三步:推送代码
44+
45+
```bash
46+
# 添加新文件
47+
git add .github/workflows/deploy-docs.yml
48+
git add docs/requirements.txt
49+
50+
# 提交更改
51+
git commit -m "feat: 添加 GitHub Pages 自动部署配置,移除 Jupyter Notebook 引用"
52+
53+
# 推送到远程仓库
54+
git push origin main
55+
```
56+
57+
### 第四步:等待部署完成
58+
59+
1. 访问:https://github.com/modelscope/RM-Gallery/actions
60+
2. 查看 "Deploy MkDocs to GitHub Pages" 工作流状态
61+
3. 等待约 2-5 分钟完成部署
62+
4. 访问:https://modelscope.github.io/RM-Gallery/
63+
64+
## 📝 注意事项
65+
66+
1. **已删除的文件**
67+
- `docs/examples` 符号链接已删除
68+
- 这意味着 `examples/` 目录下的 `.ipynb` 文件不会被包含在文档中
69+
70+
2. **已移除的依赖**
71+
- `mkdocs-jupyter` 插件已从配置中移除
72+
- 文档不再支持直接渲染 Jupyter Notebook
73+
74+
3. **文档构建**
75+
- 本地测试构建成功 ✅
76+
- 构建时间约 3.5 秒
77+
- 没有 ipynb 相关的警告
78+
79+
## 🔍 本地测试
80+
81+
如需在推送前本地预览:
82+
83+
```bash
84+
# 安装依赖
85+
pip install -r docs/requirements.txt
86+
87+
# 启动本地服务器
88+
mkdocs serve
89+
90+
# 访问 http://127.0.0.1:8000
91+
```
92+
93+
## 📊 变更文件列表
94+
95+
```
96+
新增:
97+
.github/workflows/deploy-docs.yml
98+
docs/requirements.txt
99+
DEPLOY_SUMMARY.md
100+
101+
修改:
102+
mkdocs.yml (移除 mkdocs-jupyter 插件)
103+
104+
删除:
105+
docs/examples (符号链接)
106+
```
107+
108+
---
109+
110+
配置完成!现在可以推送代码到 GitHub 触发自动部署了。
111+

docs/examples

Lines changed: 0 additions & 1 deletion
This file was deleted.

docs/requirements.txt

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
mkdocs>=1.5.0
2+
mkdocs-material>=9.0.0
3+
mkdocstrings[python]>=0.24.0
4+
pymdown-extensions>=10.0
5+
mkdocs-shadcn>=0.1.0
6+

mkdocs.yml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,6 @@ plugins:
6767
min_search_length: 2
6868
prebuild_index: true
6969
indexing: 'full'
70-
- mkdocs-jupyter
7170
- mkdocstrings:
7271
handlers:
7372
python:

0 commit comments

Comments
 (0)