mirror of
https://github.com/orbbec/OrbbecSDK_ROS2.git
synced 2026-10-08 22:07:46 +08:00
161 lines
5.1 KiB
Markdown
161 lines
5.1 KiB
Markdown
# 文档项目结构检查与修复总结
|
||
|
||
## 项目目标
|
||
创建英文版和中文版两个独立的 Sphinx 文档站点。
|
||
|
||
## 原始问题
|
||
|
||
### 1. 中文版缺失的关键文件
|
||
- ❌ `conf.py` - Sphinx 配置文件
|
||
- ❌ `index.rst` - 主索引文件
|
||
- ❌ `Makefile` - Linux/Mac 构建脚本
|
||
- ❌ `make.bat` - Windows 构建脚本
|
||
- ❌ `requirements.txt` - Python 依赖列表
|
||
|
||
### 2. 配置文件中的错误
|
||
- ❌ 英文版 `conf.py` 中 `github_doc_root` 未定义但被引用
|
||
- ❌ 英文版 `conf.py` 中路径使用 `source/images` 但实际目录是 `source/image`
|
||
|
||
## 修复内容
|
||
|
||
### ✅ 为中文版创建的文件
|
||
|
||
#### 1. `/docs/zh/conf.py`
|
||
- 项目名称：`OrbbecSDK V2 ROS2 封装`
|
||
- 语言设置：`language = 'zh_CN'`
|
||
- 版权信息：`奥比中光科技集团股份有限公司`
|
||
- 时间格式：`%Y年%m月%d日 %H:%M:%S`
|
||
- 图片路径：`source/image`（与实际目录结构一致）
|
||
- 修复了 `github_doc_root` 未定义的问题
|
||
|
||
#### 2. `/docs/zh/index.rst`
|
||
- 主文档标题：`OrbbecSDK V2 ROS2 封装文档`
|
||
- 包含所有章节的 toctree：
|
||
- 1_overview - 概览
|
||
- 2_installation - 安装
|
||
- 3_quickstarts - 快速入门
|
||
- 4_application_guide - 应用指南
|
||
- 5_advanced_guide - 高级指南
|
||
- 6_benchmark - 基准测试
|
||
- 7_developer_guide - 开发者指南
|
||
- 8_FAQ - 常见问题
|
||
|
||
#### 3. `/docs/zh/Makefile`
|
||
- Linux/Mac 下构建文档的标准 Makefile
|
||
|
||
#### 4. `/docs/zh/make.bat`
|
||
- Windows 下构建文档的批处理脚本
|
||
|
||
#### 5. `/docs/zh/requirements.txt`
|
||
- 包含必需的 Python 依赖包：
|
||
- sphinx>=4.0.0
|
||
- sphinx_rtd_theme>=1.0.0
|
||
- recommonmark>=0.7.1
|
||
- sphinx-markdown-tables>=0.0.15
|
||
- myst-parser>=0.18.0
|
||
|
||
### ✅ 修复英文版的问题
|
||
|
||
#### 1. `/docs/en/conf.py`
|
||
- 修复 `html_static_path` 和 `html_extra_path` 从 `source/images` 改为 `source/image`
|
||
- 注释掉未定义的 `github_doc_root` 相关代码
|
||
|
||
## 当前目录结构
|
||
|
||
```
|
||
docs/
|
||
├── en/ # 英文文档
|
||
│ ├── conf.py # ✅ Sphinx 配置（已修复）
|
||
│ ├── index.rst # ✅ 主索引
|
||
│ ├── Makefile # ✅ 构建脚本
|
||
│ ├── make.bat # ✅ Windows 脚本
|
||
│ ├── requirements.txt # ✅ 依赖列表
|
||
│ └── source/ # 源文件目录
|
||
│ ├── _static/ # 静态资源
|
||
│ ├── _templates/ # 模板
|
||
│ ├── image/ # 图片目录
|
||
│ ├── 1_overview/ # 概览章节
|
||
│ ├── 2_installation/ # 安装章节
|
||
│ ├── 3_quickstarts/ # 快速入门
|
||
│ ├── 4_application_guide/ # 应用指南
|
||
│ ├── 5_advanced_guide/ # 高级指南
|
||
│ ├── 6_benchmark/ # 基准测试
|
||
│ ├── 7_developer_guide/ # 开发者指南
|
||
│ └── 8_FAQ/ # 常见问题
|
||
│
|
||
└── zh/ # 中文文档
|
||
├── conf.py # ✅ Sphinx 配置（新建）
|
||
├── index.rst # ✅ 主索引（新建）
|
||
├── Makefile # ✅ 构建脚本（新建）
|
||
├── make.bat # ✅ Windows 脚本（新建）
|
||
├── requirements.txt # ✅ 依赖列表（新建）
|
||
└── source/ # 源文件目录
|
||
├── _static/ # 静态资源
|
||
├── _templates/ # 模板
|
||
├── image/ # 图片目录
|
||
├── 1_overview/ # 概览章节
|
||
├── 2_installation/ # 安装章节
|
||
├── 3_quickstarts/ # 快速入门
|
||
├── 4_application_guide/ # 应用指南
|
||
├── 5_advanced_guide/ # 高级指南
|
||
├── 6_benchmark/ # 基准测试
|
||
├── 7_developer_guide/ # 开发者指南
|
||
└── 8_FAQ/ # 常见问题
|
||
```
|
||
|
||
## 如何构建文档
|
||
|
||
### 安装依赖
|
||
```bash
|
||
# 英文版
|
||
cd docs/en
|
||
pip install -r requirements.txt
|
||
|
||
# 中文版
|
||
cd docs/zh
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 构建 HTML 文档
|
||
|
||
#### Linux/Mac
|
||
```bash
|
||
# 英文版
|
||
cd docs/en
|
||
make html
|
||
|
||
# 中文版
|
||
cd docs/zh
|
||
make html
|
||
```
|
||
|
||
#### Windows
|
||
```bash
|
||
# 英文版
|
||
cd docs/en
|
||
make.bat html
|
||
|
||
# 中文版
|
||
cd docs/zh
|
||
make.bat html
|
||
```
|
||
|
||
### 查看生成的文档
|
||
- 英文版：`docs/en/_build/html/index.html`
|
||
- 中文版：`docs/zh/_build/html/index.html`
|
||
|
||
## 注意事项
|
||
|
||
1. **目录结构正确**：英文版和中文版都采用相同的目录结构，便于维护
|
||
2. **独立配置**：两个版本有独立的配置文件，可以分别自定义
|
||
3. **共享资源**：_static 和 image 目录在两个版本间共享相同的资源
|
||
4. **语言设置**：
|
||
- 英文版：`language = 'en'`
|
||
- 中文版：`language = 'zh_CN'`
|
||
|
||
## 后续建议
|
||
|
||
1. 如果需要配置 GitHub 仓库链接，可以在 `conf.py` 中取消注释并设置 `github_doc_root` 变量
|
||
2. 考虑添加自动化构建脚本，同时构建两个版本
|
||
3. 可以在项目根目录添加一个主 README 文件，说明如何访问两个语言版本的文档
|