# 文档贡献指南

本指南说明如何为 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 文档做出的贡献！** 🙏