OrbbecSDK_ROS2/docs/PROJECT_STRUCTURE_SUMMARY.md

文档项目结构检查与修复总结

项目目标

创建英文版和中文版两个独立的 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/               # 常见问题

如何构建文档

安装依赖

# 英文版
cd docs/en
pip install -r requirements.txt

# 中文版
cd docs/zh
pip install -r requirements.txt

构建 HTML 文档

Linux/Mac

# 英文版
cd docs/en
make html

# 中文版
cd docs/zh
make html

Windows

# 英文版
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 文件，说明如何访问两个语言版本的文档