247 lines
5.3 KiB
Markdown
247 lines
5.3 KiB
Markdown
# 文档贡献指南
|
||
|
||
本指南说明如何为 ARCS SDK 贡献高质量的组件文档和示例文档。
|
||
|
||
## 📋 文档结构概览
|
||
|
||
### Components 组件文档
|
||
```
|
||
arcs-sdk/components/
|
||
├── <component_name>/ # 组件目录
|
||
│ ├── README.md # 组件文档（必需）
|
||
│ ├── CMakeLists.txt # 构建配置
|
||
│ ├── Kconfig # 配置选项
|
||
│ ├── include/ # 头文件
|
||
│ └── src/ # 源代码
|
||
```
|
||
|
||
### Samples 示例文档
|
||
```
|
||
arcs-sdk/samples/
|
||
├── <category>/ # 分类目录
|
||
│ ├── <sample_name>/ # 示例项目
|
||
│ │ ├── CMakeLists.txt # 构建配置
|
||
│ │ ├── sample.yaml # 测试配置（必需）
|
||
│ │ ├── README.md # 示例文档（推荐）
|
||
│ │ ├── prj.conf # 项目配置
|
||
│ │ ├── Kconfig # 配置选项
|
||
│ │ └── src/ # 源代码
|
||
│ └── index_zh.rst # 分类索引
|
||
```
|
||
|
||
## 🔧 组件文档编写指南
|
||
|
||
### 文档模板结构
|
||
|
||
每个组件的 `README.md` 应包含以下标准章节：
|
||
|
||
```markdown
|
||
# [组件名称] 组件
|
||
|
||
[组件简介 - 一句话概括组件功能]
|
||
|
||
## 📖 组件概述
|
||
|
||
### 主要功能
|
||
- **功能1**：详细说明
|
||
- **功能2**：详细说明
|
||
|
||
### 支持的硬件/协议
|
||
| 型号/协议 | 类型 | 特殊功能 |
|
||
|-----------|------|----------|
|
||
| 项目1 | 类型 | 说明 |
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 配置项启用
|
||
### 2. 硬件配置
|
||
### 3. 设备初始化
|
||
### 4. 基本操作
|
||
|
||
## 🔧 配置选项
|
||
|
||
## 📋 API 参考
|
||
|
||
### 核心数据结构
|
||
### 主要API函数
|
||
|
||
## ⚠️ 注意事项
|
||
```
|
||
|
||
### 编写规范
|
||
|
||
#### **标题和结构**
|
||
- 使用清晰的 Markdown 标题层次（H1-H4）
|
||
- H1 用于组件名称，H2 用于主要章节，H3 用于子章节
|
||
- 使用 emoji 图标增强可读性（📖 📋 🚀 🔧 ⚠️）
|
||
|
||
#### **代码示例**
|
||
- 所有代码块必须指定语言类型：`c`、`kconfig`、`bash`等
|
||
- 提供完整的、可运行的代码示例
|
||
- 包含错误处理和边界条件检查
|
||
- 添加必要的注释说明
|
||
|
||
#### **配置说明**
|
||
- 详细说明所有 Kconfig 配置项
|
||
- 提供配置项的默认值和可选值
|
||
- 说明配置项之间的依赖关系
|
||
|
||
#### **API文档**
|
||
- 按功能分组描述API函数
|
||
- 包含函数参数、返回值说明
|
||
- 提供数据结构的完整定义
|
||
- 举例说明常见用法
|
||
|
||
#### **表格使用**
|
||
- 使用表格组织配置项、硬件支持等信息
|
||
- 保持表格简洁易读
|
||
- 包含必要的说明列
|
||
|
||
## 📝 示例文档编写指南
|
||
|
||
### 示例项目结构
|
||
|
||
每个示例项目必须包含：
|
||
|
||
#### **必需文件**
|
||
- `sample.yaml` - 测试配置文件
|
||
- `CMakeLists.txt` - 构建配置
|
||
- `src/main.c` - 主程序源码
|
||
|
||
#### **推荐文件**
|
||
- `README.md` - 示例说明文档
|
||
- `prj.conf` - 项目配置
|
||
- `Kconfig` - 自定义配置项
|
||
- `build.sh` - 构建脚本
|
||
|
||
### 示例文档模板
|
||
|
||
```markdown
|
||
# [示例名称]
|
||
|
||
[示例功能简介]
|
||
|
||
## 📖 示例说明
|
||
|
||
### 功能演示
|
||
- 演示功能1
|
||
- 演示功能2
|
||
|
||
### 硬件要求
|
||
- 硬件要求说明
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 构建项目
|
||
### 2. 烧录运行
|
||
### 3. 查看输出
|
||
|
||
## 🔧 配置说明
|
||
|
||
## 📋 代码解析
|
||
|
||
### 关键代码段
|
||
|
||
## 🔍 预期输出
|
||
|
||
## ⚠️ 注意事项
|
||
```
|
||
|
||
## 📚 文档索引管理
|
||
|
||
### 组件索引更新
|
||
|
||
在 `arcs-sdk/components/index_zh.rst` 中添加新组件：
|
||
|
||
```rst
|
||
.. _components:
|
||
|
||
组件
|
||
====
|
||
|
||
.. toctree::
|
||
:maxdepth: 1
|
||
|
||
display/README.md
|
||
touch/README.md
|
||
<new_component>/README.md # 新增组件
|
||
```
|
||
|
||
### 示例索引更新
|
||
|
||
在相应分类的 `index_zh.rst` 中添加新示例：
|
||
|
||
```rst
|
||
.. _samples_category:
|
||
|
||
[分类名称]
|
||
==========
|
||
|
||
.. toctree::
|
||
:maxdepth: 1
|
||
|
||
existing_sample/README.md
|
||
new_sample/README.md # 新增示例
|
||
```
|
||
|
||
## ✅ 质量检查清单
|
||
|
||
### 组件文档检查
|
||
- [ ] 包含完整的功能概述
|
||
- [ ] 提供清晰的快速开始指南
|
||
- [ ] 详细说明所有配置选项
|
||
- [ ] 包含完整的API参考
|
||
- [ ] 包含注意事项和限制说明
|
||
- [ ] 更新了组件索引文件
|
||
|
||
### 示例文档检查
|
||
- [ ] `sample.yaml` 配置正确
|
||
- [ ] 构建脚本正常工作
|
||
- [ ] 代码风格符合项目规范
|
||
- [ ] 包含清晰的使用说明
|
||
- [ ] 预期输出描述准确
|
||
- [ ] 更新了相应的索引文件
|
||
|
||
### 通用质量要求
|
||
- [ ] 中文表达规范，语句通顺
|
||
- [ ] Markdown 格式正确
|
||
- [ ] 链接和引用有效
|
||
- [ ] 图片和表格清晰
|
||
- [ ] 拼写和语法无误
|
||
|
||
## 🛠️ 本地测试
|
||
|
||
### 文档构建测试
|
||
```bash
|
||
cd arcs-sdk/docs
|
||
make zh # 构建中文文档
|
||
# 检查 output/zh/html/ 中的生成结果
|
||
```
|
||
|
||
### 示例构建测试
|
||
```bash
|
||
cd arcs-sdk/samples/<category>/<sample_name>
|
||
./build.sh # 构建示例
|
||
# 检查构建是否成功
|
||
```
|
||
|
||
## 📬 提交流程
|
||
|
||
1. **创建分支**：基于主分支创建功能分支
|
||
2. **编写文档**：按照本指南编写文档
|
||
3. **本地测试**：确保文档构建和示例编译正常
|
||
4. **质量检查**：使用检查清单验证文档质量
|
||
5. **提交PR**：创建Pull Request并请求代码审查
|
||
|
||
## 🤝 寻求帮助
|
||
|
||
如有文档编写疑问，可以：
|
||
- 参考现有优质文档（如 `display` 组件）
|
||
- 查阅本项目的代码风格指南
|
||
- 在项目讨论区提问
|
||
- 联系维护团队获取支持
|
||
|
||
---
|
||
|
||
**感谢您为 ARCS SDK 文档做出的贡献！** 🙏
|