Skip to content

Commit 764b31e

Browse files
amumu96amumu96
authored
Merge pull request #4 from xorbitsai/doc/add_doc
feat: 添加GitHub Pages文档部署工作流和相关配置文件
2 parents 26b1284 + 1e8876c commit 764b31e

File tree

10 files changed

+246
-2
lines changed

10 files changed

+246
-2
lines changed

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

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
name: Deploy Documentation to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [ main, master ]
6+
pull_request:
7+
branches: [ main, master ]
8+
workflow_dispatch:
9+
10+
permissions:
11+
contents: read
12+
pages: write
13+
id-token: write
14+
15+
concurrency:
16+
group: "pages"
17+
cancel-in-progress: false
18+
19+
jobs:
20+
build:
21+
runs-on: ubuntu-latest
22+
23+
steps:
24+
- name: Checkout repository
25+
uses: actions/checkout@v4
26+
27+
- name: Set up Python
28+
uses: actions/setup-python@v4
29+
with:
30+
python-version: '3.9'
31+
32+
- name: Install dependencies
33+
run: |
34+
python -m pip install --upgrade pip
35+
pip install -r docs/requirements.txt
36+
37+
- name: Build multilingual documentation
38+
run: |
39+
cd docs
40+
python build_multilang.py
41+
42+
- name: Setup Pages
43+
uses: actions/configure-pages@v3
44+
45+
- name: Upload artifact
46+
uses: actions/upload-pages-artifact@v2
47+
with:
48+
path: docs/build/html
49+
50+
deploy:
51+
environment:
52+
name: github-pages
53+
url: ${{ steps.deployment.outputs.page_url }}
54+
runs-on: ubuntu-latest
55+
needs: build
56+
if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
57+
58+
steps:
59+
- name: Deploy to GitHub Pages
60+
id: deployment
61+
uses: actions/deploy-pages@v2

‎DEPLOYMENT.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# GitHub Pages 部署指南
2+
3+
本文档说明如何将 Xorbits Inference Enterprise 文档部署到 GitHub Pages。
4+
5+
## 🚀 自动部署
6+
7+
### 前置条件
8+
9+
1. **GitHub 仓库设置**
10+
- 确保仓库是公开的（或者有 GitHub Pro/Team 账户用于私有仓库）
11+
- 在仓库设置中启用 GitHub Pages
12+
13+
2. **GitHub Pages 配置**
14+
- 进入仓库 Settings → Pages
15+
- Source 选择 "GitHub Actions"
16+
- 保存设置
17+
18+
### 部署流程
19+
20+
当你推送代码到 `main` 或 `master` 分支时，GitHub Actions 会自动：
21+
22+
1. **安装依赖**: 安装 Python 和 Sphinx 相关包
23+
2. **构建文档**: 运行 `build_multilang.py` 生成多语言文档
24+
3. **部署到 Pages**: 将构建结果发布到 GitHub Pages
25+
26+
### 访问地址
27+
28+
部署完成后，文档将在以下地址可用：
29+
30+
- **中文文档**: `https://[username].github.io/[repository-name]/`
31+
- **英文文档**: `https://[username].github.io/[repository-name]/en/`
32+
33+
例如：
34+
- 中文: https://xorbitsai.github.io/enterprise-docs/
35+
- 英文: https://xorbitsai.github.io/enterprise-docs/en/
36+
37+
## 🔧 手动部署
38+
39+
如果需要手动部署，可以按以下步骤操作：
40+
41+
### 1. 本地构建
42+
43+
```bash
44+
cd docs
45+
python build_multilang.py
46+
```
47+
48+
### 2. 推送到 gh-pages 分支
49+
50+
```bash
51+
# 安装 ghp-import（如果还没有安装）
52+
pip install ghp-import
53+
54+
# 推送到 gh-pages 分支
55+
ghp-import -n -p -f docs/build/html
56+
```
57+
58+
## 📁 文件结构
59+
60+
```
61+
enterprise-docs/
62+
├── .github/
63+
│ └── workflows/
64+
│ └── deploy-docs.yml # GitHub Actions 工作流
65+
├── docs/
66+
│ ├── source/
67+
│ │ ├── .nojekyll # 防止 Jekyll 处理
68+
│ │ ├── conf.py # Sphinx 配置
69+
│ │ └── ... # 文档源文件
70+
│ ├── build_multilang.py # 多语言构建脚本
71+
│ ├── requirements.txt # Python 依赖
72+
│ └── build/
73+
│ └── html/ # 构建输出
74+
│ ├── .nojekyll # 复制到输出目录
75+
│ ├── index.html # 中文首页
76+
│ └── en/ # 英文版本
77+
│ └── index.html
78+
├── README.md # 项目说明
79+
└── DEPLOYMENT.md # 本文档
80+
```
81+
82+
## 🛠️ 故障排除
83+
84+
### 常见问题
85+
86+
1. **构建失败**
87+
- 检查 `requirements.txt` 中的依赖版本
88+
- 查看 GitHub Actions 日志中的错误信息
89+
90+
2. **页面显示异常**
91+
- 确保 `.nojekyll` 文件存在于输出目录
92+
- 检查相对路径是否正确
93+
94+
3. **多语言切换不工作**
95+
- 确认 `switcher.json` 文件已正确生成
96+
- 检查语言切换器配置
97+
98+
### 调试步骤
99+
100+
1. **本地测试**
101+
```bash
102+
cd docs
103+
python build_multilang.py
104+
cd build/html
105+
python -m http.server 8080
106+
```
107+
108+
2. **检查构建日志**
109+
- 在 GitHub 仓库的 Actions 标签页查看构建日志
110+
- 查找错误信息和警告
111+
112+
3. **验证文件**
113+
```bash
114+
# 检查关键文件是否存在
115+
ls docs/build/html/.nojekyll
116+
ls docs/build/html/_static/switcher.json
117+
ls docs/build/html/en/_static/switcher.json
118+
```
119+
120+
## 📝 自定义配置
121+
122+
### 修改域名
123+
124+
如果使用自定义域名，需要：
125+
126+
1. 在 `docs/source/` 目录下创建 `CNAME` 文件
127+
2. 在文件中写入你的域名（如 `docs.example.com`）
128+
3. 修改 `build_multilang.py` 复制 CNAME 文件到输出目录
129+
130+
### 修改基础路径
131+
132+
如果仓库名不是 `enterprise-docs`，需要：
133+
134+
1. 修改 `docs/source/conf.py` 中的 `html_baseurl`
135+
2. 更新 `switcher.json` 中的 URL 路径
136+
137+
## 🔄 更新流程
138+
139+
1. **修改文档**: 编辑 `docs/source/` 下的 `.rst` 文件
140+
2. **本地测试**: 运行 `python build_multilang.py` 验证构建
141+
3. **提交推送**: 提交更改并推送到 main 分支
142+
4. **自动部署**: GitHub Actions 自动构建和部署
143+
5. **验证结果**: 访问 GitHub Pages 地址确认更新
144+
145+
## 📊 监控
146+
147+
- **构建状态**: 查看仓库 README 中的构建徽章
148+
- **部署历史**: 在 GitHub Actions 页面查看部署历史
149+
- **访问统计**: 在 GitHub Insights 中查看页面访问情况

‎README.md‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,30 @@
11
<div align="center">
22
<img src="https://github.com/xorbitsai/inference/blob/043b673dbd93f1cd5c8d6b0bb481f8d605cd24d2/assets/xorbits-logo.png" width="180px" alt="xorbits" />
33

4-
# Xorbits Inference Enterprise
4+
# Xorbits Inference Enterprise Documentation
55

66
<p align="center">
77
<a href="./README.md"><img alt="README in English" src="https://img.shields.io/badge/English-454545?style=for-the-badge"></a>
88
<a href="./README_zh_CN.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/中文介绍-d9d9d9?style=for-the-badge"></a>
99
</p>
1010

11+
[![Deploy Documentation](https://github.com/xorbitsai/enterprise-docs/actions/workflows/deploy-docs.yml/badge.svg)](https://github.com/xorbitsai/enterprise-docs/actions/workflows/deploy-docs.yml)
12+
[![GitHub Pages](https://img.shields.io/badge/GitHub%20Pages-Live-brightgreen)](https://xorbitsai.github.io/enterprise-docs/)
13+
1114
</div>
12-
<br />
15+
<br />
16+
17+
## 📚 Online Documentation
18+
19+
- **中文文档**: [https://xorbitsai.github.io/enterprise-docs/](https://xorbitsai.github.io/enterprise-docs/)
20+
- **English Documentation**: [https://xorbitsai.github.io/enterprise-docs/en/](https://xorbitsai.github.io/enterprise-docs/en/)
21+
22+
## 🚀 Features
23+
24+
This repository contains comprehensive documentation for Xorbits Inference Enterprise, including:
25+
26+
- **Multi-platform Support**: NVIDIA, MindIE, Hygon hardware platforms
27+
- **Deployment Guides**: Single-node and multi-node deployment configurations
28+
- **Enterprise Features**: License management, performance monitoring, troubleshooting
29+
- **Multilingual**: Full Chinese and English documentation
30+
- **Interactive**: Live examples and configuration templates

‎docs/build/html/.doctrees/environment.pickle‎

101 Bytes
Binary file not shown.

‎docs/build/html/en/.doctrees/environment.pickle‎

709 Bytes
Binary file not shown.

‎docs/build/locale/.doctrees/environment.pickle‎

0 Bytes
Binary file not shown.

‎docs/build/locale/.doctrees/getting_started/index.doctree‎

0 Bytes
Binary file not shown.

‎docs/build_multilang.py‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,14 @@ def build_language(lang, output_dir):
4242
print(f"Successfully built {lang} documentation")
4343
return True
4444

45+
def copy_nojekyll_file():
46+
"""复制.nojekyll文件到输出目录"""
47+
nojekyll_source = Path("source/.nojekyll")
48+
if nojekyll_source.exists():
49+
# 复制到中文版本根目录
50+
shutil.copy2(nojekyll_source, "build/html/.nojekyll")
51+
print("Copied .nojekyll to build/html/")
52+
4553
def update_switcher_config():
4654
"""更新语言切换器配置"""
4755
switcher_config = [
@@ -97,6 +105,10 @@ def main():
97105
if not build_language('en', 'build/html/en'):
98106
return False
99107

108+
# 复制.nojekyll文件
109+
print("\n=== Copying .nojekyll file ===")
110+
copy_nojekyll_file()
111+
100112
# 更新语言切换器配置
101113
print("\n=== Updating language switcher ===")
102114
update_switcher_config()

‎docs/requirements.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
sphinx>=7.0.0
2+
sphinx-rtd-theme>=1.3.0
3+
sphinx-intl>=2.1.0
4+
sphinx-autosummary-accessors>=2023.4.0

‎docs/source/.nojekyll‎

Whitespace-only changes.

0 commit comments

Comments
 (0)