147 lines
4.2 KiB
Markdown
147 lines
4.2 KiB
Markdown
# 本地文档构建指南
|
||
|
||
本文档指导您如何在本地环境中构建和生成项目文档。
|
||
|
||
## 文档架构说明
|
||
|
||
本项目采用**Sphinx + Doxygen**混合架构生成多语言技术文档，支持中英文双语输出。
|
||
|
||
### 架构组成
|
||
|
||
```
|
||
docs/
|
||
├── zh/ # 中文文档源文件
|
||
│ ├── conf.py # Sphinx中文配置文件
|
||
│ ├── index.rst # 中文文档主页
|
||
│ ├── get_started.rst # 快速开始指南
|
||
│ ├── components/ # 组件文档
|
||
│ └── api_doc.md # API文档入口
|
||
├── doxygen/ # Doxygen配置与定制
|
||
│ ├── Doxyfile # Doxygen配置文件
|
||
│ ├── mainpage.md # API文档主页
|
||
│ └── custom/ # 自定义样式和模板
|
||
├── _ext/ # Sphinx扩展插件
|
||
│ ├── doxyrunner.py # Doxygen集成插件
|
||
│ └── external_content.py # 外部内容处理
|
||
├── assets/ # 静态资源文件
|
||
├── requirements.txt # Python依赖列表
|
||
├── Makefile # 构建配置
|
||
└── README.md # 本指南
|
||
```
|
||
|
||
### 文档生成流程
|
||
|
||
1. **Sphinx处理**：处理RST/MD格式的用户文档
|
||
2. **Doxygen集成**：自动提取代码注释生成API文档
|
||
3. **多语言支持**：通过`make en`/`make zh`生成对应语言版本
|
||
4. **输出统一**：最终在`output/`目录生成完整的HTML文档
|
||
|
||
### 技术特点
|
||
|
||
- **🌐 多语言支持**：中英文双语文档生成
|
||
- **📚 混合文档**：结合手写文档和自动API文档
|
||
- **🔧 可扩展**：通过`_ext/`目录的插件系统支持自定义功能
|
||
- **📱 响应式**：使用Read the Docs主题，支持移动端阅读
|
||
|
||
## 环境准备
|
||
|
||
### 安装系统依赖
|
||
|
||
本文档构建依赖 Doxygen 工具来生成 API 文档，请先安装：
|
||
|
||
**Ubuntu/Debian:**
|
||
```bash
|
||
sudo apt-get install doxygen
|
||
```
|
||
|
||
**其他系统:**
|
||
请访问 [Doxygen 官网](https://www.doxygen.nl/download.html) 下载对应平台的安装包。
|
||
|
||
### 安装 Python 依赖
|
||
|
||
在开始构建文档之前，还需要安装必要的 Python 依赖包：
|
||
|
||
```bash
|
||
pip install --user -r requirements.txt
|
||
```
|
||
|
||
## 构建文档
|
||
|
||
### 生成文档
|
||
|
||
1. 切换到项目的 `docs` 目录：
|
||
```bash
|
||
cd docs
|
||
```
|
||
|
||
2. 执行构建命令：
|
||
|
||
**构建所有语言版本（推荐）：**
|
||
```bash
|
||
make
|
||
```
|
||
|
||
**仅构建中文文档：**
|
||
```bash
|
||
make zh
|
||
```
|
||
|
||
**仅构建英文文档 (暂不支持)：**
|
||
```bash
|
||
make en
|
||
```
|
||
|
||
**将 Sphinx 警告视为错误：**
|
||
```bash
|
||
make SPHINXOPTS="-W"
|
||
```
|
||
> 利用 `SPHINXOPTS` 变量向 `sphinx-build` 追加 `-W` 参数，任何警告都会使构建失败；可与 `make`、`make zh` 等目标同时使用，例如 `make zh SPHINXOPTS="-W"`。
|
||
|
||
**清理构建缓存：**
|
||
```bash
|
||
make clean
|
||
```
|
||
|
||
### 查看生成结果
|
||
|
||
文档构建完成后，生成的文档文件将保存在 `output` 目录中：
|
||
|
||
```
|
||
output/
|
||
├── zh/ # 中文文档
|
||
│ └── html/
|
||
│ └── index.html
|
||
└── en/ # 英文文档
|
||
└── html/
|
||
└── index.html
|
||
```
|
||
|
||
您可以通过浏览器打开对应语言目录下的 `index.html` 文件来查看文档内容。
|
||
|
||
### 故障排除
|
||
|
||
**常见问题：**
|
||
|
||
- **依赖缺失**：确保已安装 `requirements.txt` 中的所有依赖包
|
||
- **权限问题**：如果使用 `--user` 安装依赖后仍有问题，可尝试使用虚拟环境
|
||
- **构建失败**：使用 `make clean` 清理缓存后重新构建
|
||
|
||
## 📚 文档贡献
|
||
|
||
### 贡献指南
|
||
|
||
如果您想为 ARCS SDK 贡献文档，请参阅 [文档贡献指南](CONTRIBUTING.md)，其中包含：
|
||
|
||
- **组件文档编写规范**：标准模板和编写要求
|
||
- **示例文档编写指南**：示例项目的文档化要求
|
||
- **文档索引管理**：如何正确添加新文档到索引
|
||
- **质量检查清单**：确保文档质量的检查要点
|
||
- **提交流程**：从编写到发布的完整流程
|
||
|
||
### 主要贡献领域
|
||
|
||
- **组件文档** (`components/`): 为SDK组件编写完整的使用文档
|
||
- **示例文档** (`samples/`): 为示例项目提供清晰的说明文档
|
||
- **API文档**: 通过代码注释改进自动生成的API文档
|
||
|