chenyuxuan/arcs

Fork 0

Files

yuuux d1d25a09e7 chore: migrate project into clean repository

2026-08-13 16:50:52 +08:00

5.3 KiB

Raw Permalink Blame History

文档贡献指南

本指南说明如何为 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 应包含以下标准章节：

# [组件名称] 组件

[组件简介 - 一句话概括组件功能]

## 📖 组件概述

### 主要功能
- **功能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 - 主程序源码

示例文档模板

# [示例名称]

[示例功能简介]

## 📖 示例说明

### 功能演示
- 演示功能1
- 演示功能2

### 硬件要求
- 硬件要求说明

## 🚀 快速开始

### 1. 构建项目
### 2. 烧录运行
### 3. 查看输出

## 🔧 配置说明

## 📋 代码解析

### 关键代码段

## 🔍 预期输出

## ⚠️ 注意事项

📚 文档索引管理

组件索引更新

在 arcs-sdk/components/index_zh.rst 中添加新组件：

.. _components:

组件
====

.. toctree::
    :maxdepth: 1

    display/README.md
    touch/README.md
    <new_component>/README.md    # 新增组件

示例索引更新

在相应分类的 index_zh.rst 中添加新示例：

.. _samples_category:

[分类名称]
==========

.. toctree::
    :maxdepth: 1

    existing_sample/README.md
    new_sample/README.md         # 新增示例

✅ 质量检查清单

组件文档检查

包含完整的功能概述
提供清晰的快速开始指南
详细说明所有配置选项
包含完整的API参考
包含注意事项和限制说明
更新了组件索引文件

示例文档检查

sample.yaml 配置正确
构建脚本正常工作
代码风格符合项目规范
包含清晰的使用说明
预期输出描述准确
更新了相应的索引文件

通用质量要求

中文表达规范，语句通顺
Markdown 格式正确
链接和引用有效
图片和表格清晰
拼写和语法无误

🛠️ 本地测试

文档构建测试

cd arcs-sdk/docs
make zh                      # 构建中文文档
# 检查 output/zh/html/ 中的生成结果

示例构建测试

cd arcs-sdk/samples/<category>/<sample_name>
./build.sh                   # 构建示例
# 检查构建是否成功

📬 提交流程

创建分支：基于主分支创建功能分支
编写文档：按照本指南编写文档
本地测试：确保文档构建和示例编译正常
质量检查：使用检查清单验证文档质量
提交PR：创建Pull Request并请求代码审查

🤝 寻求帮助

如有文档编写疑问，可以：

参考现有优质文档（如 display 组件）
查阅本项目的代码风格指南
在项目讨论区提问
联系维护团队获取支持

感谢您为 ARCS SDK 文档做出的贡献！ 🙏

5.3 KiB Raw Permalink Blame History Unescape Escape