1573 lines
34 KiB
Markdown
1573 lines
34 KiB
Markdown
# ARCS SDK 示例文档编写规范（AI 辅助版）
|
||
|
||
> 本规范用于指导 AI 生成和检查 ARCS SDK 示例文档，确保所有示例文档风格统一、信息完整、格式规范。
|
||
|
||
**版本**: 2.0
|
||
**日期**: 2025-01-14
|
||
**维护者**: ARCS SDK 团队
|
||
**适用范围**: 所有 samples/ 目录下的示例文档（README.md 或 README.rst）
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [规范概述](#规范概述)
|
||
2. [文档结构规范](#文档结构规范)
|
||
3. [各章节详细规范](#各章节详细规范)
|
||
4. [不同类型示例的差异](#不同类型示例的差异)
|
||
5. [格式规范](#格式规范)
|
||
6. [AI 生成文档指南](#ai-生成文档指南)
|
||
7. [AI 审查文档清单](#ai-审查文档清单)
|
||
|
||
---
|
||
|
||
## 规范概述
|
||
|
||
### 核心原则
|
||
|
||
1. **结构一致性**: 所有示例遵循统一的章节结构和顺序
|
||
2. **信息完整性**: 必需章节不可缺失，关键信息必须包含
|
||
3. **格式统一性**: 支持 Markdown 或 reStructuredText 格式，格式内部保持一致
|
||
4. **语言规范性**: 中英文使用场景明确，术语表达一致
|
||
|
||
### 文档格式说明
|
||
|
||
本规范支持两种文档格式：
|
||
|
||
- **Markdown (README.md)**: 推荐格式，语法简洁，易于编写
|
||
- **reStructuredText (README.rst)**: 可选格式，适合需要复杂文档结构的场景
|
||
|
||
两种格式的章节结构和内容要求完全相同，仅语法有所差异。本文档主要以 Markdown 语法为例，RST 格式请参考对应的语法规范。
|
||
|
||
### 示例分类
|
||
|
||
| 类型 | 路径 | 特征 | 代表示例 |
|
||
|------|------|------|----------|
|
||
| **设备驱动** | `samples/drivers/devices/` | 使用 LISA 设备 API，需硬件连接说明 | lisa_gpio, lisa_uart |
|
||
| **组件模块** | `samples/modules/` | 系统组件/中间件，可能无硬件依赖 | sys_heap, lisa_shell |
|
||
| **网络示例** | `samples/network/` | 网络协议/通信，需环境配置 | http, wifi_manager |
|
||
| **HAL 驱动** | `samples/drivers/hal/` | 底层硬件抽象层，需硬件连接 | gpio, uart, spi |
|
||
|
||
---
|
||
|
||
## 文档结构规范
|
||
|
||
### 标准章节结构（按顺序）
|
||
|
||
#### 必需章节（所有示例）
|
||
|
||
| 序号 | 章节 | 标题格式 | 必需性 | 适用范围 |
|
||
|------|------|----------|--------|----------|
|
||
| 1 | 标题 | `# {模块名} {功能}示例` | ✅ 必需 | 所有 |
|
||
| 2 | 功能说明 | `## 功能说明` | ✅ 必需 | 所有 |
|
||
| 3 | 硬件连接 | `## 硬件连接` | ✅ 必需 | 所有 |
|
||
| 4 | 示例内容/步骤 | `## 示例内容` 或 `## 示例步骤` | ✅ 必需 | 所有 |
|
||
| 5 | 编译 | `## 编译` | ✅ 必需 | 所有 |
|
||
| 6 | 烧录 | `## 烧录` | ✅ 必需 | 所有 |
|
||
| 7 | 预期输出 | `## 预期输出` | ✅ 必需 | 所有 |
|
||
| 8 | 核心 API | `## 核心 API` | ⭐ 强烈推荐 | Devices, Modules |
|
||
| 9 | 关键代码 | `## 关键代码` | ⭐ 强烈推荐 | 所有 |
|
||
| 10 | 注意事项 | `## 注意事项` | ⭐ 强烈推荐 | 所有 |
|
||
|
||
#### 可选章节（根据需要）
|
||
|
||
| 章节 | 标题格式 | 使用场景 |
|
||
|------|----------|----------|
|
||
| 新特性 | `### 新特性` | 高级示例，展示技术优势 |
|
||
| 使用场景 | `## 使用场景` | 需说明技术选型时 |
|
||
| 配置说明 | `## 配置说明` | 有重要配置参数时 |
|
||
| 功能详解 | `## {功能}说明` | 需解释工作原理时 |
|
||
| 验证方法 | `## 验证方法` | 输出不可直接观察时 |
|
||
| 测试环境 | `## 测试环境准备` | 需复杂环境配置时 |
|
||
|
||
### 章节顺序规则
|
||
|
||
**固定顺序（不可调整）:**
|
||
|
||
```
|
||
1. 标题（H1）
|
||
2. 功能说明（H2）
|
||
└── 新特性（H3，可选）
|
||
3. 硬件连接（H2）
|
||
4. 使用场景/测试环境（H2，可选）
|
||
5. 示例内容/步骤（H2）
|
||
6. 编译（H2）
|
||
7. 烧录（H2）
|
||
8. 预期输出（H2）
|
||
9. 核心 API（H2，推荐）
|
||
10. 功能详解（H2，可选）
|
||
11. 关键代码（H2，推荐）
|
||
12. 配置说明（H2，可选）
|
||
13. 验证方法（H2，可选）
|
||
14. 注意事项（H2，推荐）
|
||
15. 相关文档（H2，可选）
|
||
```
|
||
|
||
---
|
||
|
||
## 各章节详细规范
|
||
|
||
### 1. 标题（H1）
|
||
|
||
**格式模式:**
|
||
|
||
```markdown
|
||
# {模块名称} {功能描述}示例{（可选说明）}
|
||
```
|
||
|
||
**规则:**
|
||
|
||
- **模块名称**: 使用正式名称（LISA GPIO、系统堆管理、HTTP 客户端）
|
||
- **功能描述**: 简洁明了（基础输出、内存分配、同步接收）
|
||
- **可选说明**: 括号中注明特殊模式（DMA 模式、中断模式）
|
||
|
||
**正确示例:**
|
||
|
||
```markdown
|
||
✅ # LISA GPIO 基础输出示例
|
||
✅ # 系统堆管理基础示例
|
||
✅ # LISA UART 同步接收示例（DMA 模式）
|
||
✅ # HTTP 客户端基础示例
|
||
```
|
||
|
||
**错误示例:**
|
||
|
||
```markdown
|
||
❌ # gpio example (未使用中文，未规范化模块名)
|
||
❌ # LISA_GPIO 基础示例 (模块名使用下划线)
|
||
❌ # GPIO 示例 (缺少 LISA 前缀)
|
||
```
|
||
|
||
### 2. 功能说明（H2，必需）
|
||
|
||
**格式:**
|
||
|
||
```markdown
|
||
## 功能说明
|
||
|
||
{第一段：核心功能说明（1-2 句话）}
|
||
|
||
{第二段：可选补充说明（技术特点/底层实现）}
|
||
```
|
||
|
||
**内容要求:**
|
||
|
||
1. **第一段**（必需）:
|
||
- 1-2 句话说明核心功能
|
||
- 40-200 字为宜
|
||
- 说明"做什么"和"怎么做"
|
||
|
||
2. **第二段**（可选）:
|
||
- 补充技术特点或实现细节
|
||
- 突出技术优势或注意事项
|
||
|
||
**正确示例:**
|
||
|
||
```markdown
|
||
## 功能说明
|
||
|
||
演示如何使用 LISA GPIO 驱动控制 LED 闪烁，通过配置引脚为输出模式，周期性输出高低电平实现 LED 的亮灭切换。
|
||
```
|
||
|
||
```markdown
|
||
## 功能说明
|
||
|
||
演示如何使用系统堆管理组件分配和释放内存，包括内部 SRAM 和外部 PSRAM 的基本操作。
|
||
```
|
||
|
||
```markdown
|
||
## 功能说明
|
||
|
||
此示例演示如何使用 LISA HTTP 客户端库进行基本的 HTTP 通信，包括：
|
||
- HTTP GET 请求
|
||
- HTTP POST 请求（普通表单数据）
|
||
- HTTP POST 请求（Chunked 传输编码）
|
||
|
||
示例通过 WiFi 连接到测试服务器，执行多个 HTTP 请求并接收响应，展示了 HTTP 客户端的基本用法。
|
||
```
|
||
|
||
**错误示例:**
|
||
|
||
```markdown
|
||
❌ ## 功能说明
|
||
|
||
This example shows... (使用英文)
|
||
|
||
❌ ## 功能说明
|
||
|
||
本示例功能强大，非常好用，可以实现各种复杂的操作... (描述过于笼统，未说明具体功能)
|
||
```
|
||
|
||
### 3. 新特性（H3，可选）
|
||
|
||
**使用时机:**
|
||
|
||
- 高级示例（DMA、中断、异步等）
|
||
- 有明显技术优势需要突出
|
||
- 与基础示例有显著差异
|
||
|
||
**格式:**
|
||
|
||
```markdown
|
||
### 新特性
|
||
|
||
- **特性1**: 简短说明
|
||
- **特性2**: 简短说明
|
||
- **特性3**: 简短说明
|
||
```
|
||
|
||
**内容要求:**
|
||
|
||
- 使用无序列表
|
||
- 每项开头用 **粗体** 标注特性名称
|
||
- 3-5 项为宜
|
||
- 每项一行，简洁明了
|
||
|
||
**正确示例:**
|
||
|
||
```markdown
|
||
### 新特性
|
||
|
||
- **DMA 硬件传输**: 无需 CPU 参与数据搬移，降低 CPU 占用
|
||
- **异步非阻塞**: 调用后立即返回，DMA 后台传输
|
||
- **事件回调通知**: 传输完成后通过中断回调通知应用层
|
||
- **适合高速率场景**: 支持高波特率连续发送，不阻塞主任务
|
||
```
|
||
|
||
### 4. 硬件连接（H2，必需）
|
||
|
||
**格式（有外部连接）:**
|
||
|
||
```markdown
|
||
## 硬件连接
|
||
|
||
- **引脚编号**: 功能说明
|
||
- **引脚编号**: 功能说明
|
||
|
||
{补充说明（可选）}
|
||
```
|
||
|
||
**格式（无外部连接）:**
|
||
|
||
```markdown
|
||
## 硬件连接
|
||
|
||
无需外部连接，{模块}为芯片内部资源。
|
||
```
|
||
|
||
**内容要求:**
|
||
|
||
1. **引脚说明**:
|
||
- 使用无序列表
|
||
- 引脚编号用 **粗体**
|
||
- 说明引脚功能和用途
|
||
|
||
2. **补充说明**:
|
||
- 连接方式、配置参数
|
||
- 外部设备要求
|
||
- 硬件注意事项
|
||
|
||
**正确示例（有连接）:**
|
||
|
||
```markdown
|
||
## 硬件连接
|
||
|
||
- **PB09**: LED 控制引脚（外接 LED 与限流电阻，ARCS-EVB 板载接口）
|
||
|
||
将 LED 正极（长脚）通过限流电阻（推荐 220Ω-1kΩ）连接到 PB09 引脚，负极（短脚）连接到 GND。
|
||
```
|
||
|
||
```markdown
|
||
## 硬件连接
|
||
|
||
- **PA2**: UART0 RX（接收）
|
||
- **PA3**: UART0 TX（发送）
|
||
|
||
连接到 PC 串口工具，配置为 **115200, 8N1, 无流控**
|
||
```
|
||
|
||
**正确示例（无连接）:**
|
||
|
||
```markdown
|
||
## 硬件连接
|
||
|
||
无需外部连接，系统堆为芯片内部资源。
|
||
```
|
||
|
||
```markdown
|
||
## 硬件连接
|
||
|
||
本示例使用芯片内部 WiFi 外设，无需额外接线。
|
||
|
||
**串口输出：**
|
||
- 串口 TX: PA3
|
||
- 波特率：921600
|
||
```
|
||
|
||
### 5. 示例内容/步骤（H2，必需）
|
||
|
||
**标题选择:**
|
||
|
||
- `## 示例内容`: 用于功能演示类示例
|
||
- `## 示例步骤`: 用于操作流程类示例
|
||
|
||
**格式:**
|
||
|
||
```markdown
|
||
## 示例内容
|
||
|
||
1. 步骤1描述
|
||
2. 步骤2描述
|
||
3. 步骤3描述
|
||
4. 步骤4描述
|
||
```
|
||
|
||
**内容要求:**
|
||
|
||
- 使用有序列表（编号列表）
|
||
- 3-6 个步骤为宜
|
||
- 每步简洁明了，突出关键操作
|
||
- 按执行顺序排列
|
||
|
||
**正确示例:**
|
||
|
||
```markdown
|
||
## 示例内容
|
||
|
||
1. 从内部 SRAM 分配 256 字节内存
|
||
2. 从外部 PSRAM 分配 1024 字节内存
|
||
3. 使用 `psram_calloc()` 分配并清零内存
|
||
4. 使用 `psram_realloc()` 重新分配内存
|
||
5. 查看堆使用统计信息
|
||
```
|
||
|
||
```markdown
|
||
## 示例步骤
|
||
|
||
1. 获取 GPIOB 设备
|
||
2. 配置 PB09 引脚为输出模式，初始电平为低
|
||
3. 循环切换引脚输出电平（高/低）
|
||
4. 每次切换间隔 1 秒，实现 LED 闪烁效果
|
||
```
|
||
|
||
### 6. 编译/运行（H2，必需）
|
||
|
||
**标题选择:**
|
||
|
||
- `## 编译`: 仅说明编译（推荐）
|
||
- `## 编译运行`: 包含编译和运行
|
||
- `## 编译` + 独立 `## 烧录`: 编译和烧录分开（推荐）
|
||
|
||
**推荐格式（使用 RST 引用）:**
|
||
|
||
```markdown
|
||
## 编译
|
||
|
||
```{eval-rst}
|
||
.. include:: /sample_build.rst
|
||
```
|
||
|
||
## 烧录
|
||
|
||
```{eval-rst}
|
||
.. include:: /sample_flash.rst
|
||
```
|
||
```
|
||
|
||
**说明:**
|
||
|
||
- 统一使用 RST 引用文件，保持格式一致性
|
||
- `/sample_build.rst` 包含标准编译命令
|
||
- `/sample_flash.rst` 包含标准烧录命令
|
||
- 分开成两个独立的 H2 章节（`## 编译` 和 `## 烧录`）
|
||
|
||
**备选格式（直接写命令）:**
|
||
|
||
如果需要特殊的编译参数或说明，可以直接写命令：
|
||
|
||
```markdown
|
||
## 编译
|
||
|
||
```bash
|
||
./build.sh -C -DBOARD=arcs_evb
|
||
```
|
||
|
||
## 烧录
|
||
|
||
```bash
|
||
./build.sh -F
|
||
```
|
||
```
|
||
|
||
**合并格式（不推荐）:**
|
||
|
||
```markdown
|
||
## 编译运行
|
||
|
||
### 编译
|
||
|
||
```{eval-rst}
|
||
.. include:: /sample_build.rst
|
||
```
|
||
|
||
### 烧录
|
||
|
||
```{eval-rst}
|
||
.. include:: /sample_flash.rst
|
||
```
|
||
```
|
||
|
||
**注意:**
|
||
- 优先使用 RST 引用格式，除非有特殊说明需要
|
||
- 编译和烧录建议分为两个独立的 H2 章节，而不是使用 H3 子章节
|
||
|
||
### 7. 预期输出（H2，必需）
|
||
|
||
**格式（单一输出源）:**
|
||
|
||
```markdown
|
||
## 预期输出
|
||
|
||
```
|
||
[I][sample] === Example Output ===
|
||
...
|
||
```
|
||
```
|
||
|
||
**格式（多个输出源）:**
|
||
|
||
```markdown
|
||
## 预期输出
|
||
|
||
**终端输出：**
|
||
```
|
||
[I][sample] === Example Output ===
|
||
...
|
||
```
|
||
|
||
**串口工具接收：**
|
||
```
|
||
Hello World
|
||
...
|
||
```
|
||
|
||
**LED 状态：**
|
||
- LED 每秒切换一次亮灭状态
|
||
```
|
||
|
||
**内容要求:**
|
||
|
||
1. **真实输出**: 必须与实际运行结果一致
|
||
2. **完整性**: 包含关键日志，可用 `...` 省略重复部分
|
||
3. **格式**: 使用代码块，保持原始格式
|
||
4. **分类**: 多个输出源用 **粗体标题** 分隔
|
||
|
||
**正确示例:**
|
||
|
||
```markdown
|
||
## 预期输出
|
||
|
||
**终端输出：**
|
||
```
|
||
=== LISA GPIO output example ===
|
||
gpiob device ready
|
||
Start toggling LED...
|
||
LED is ON
|
||
LED is OFF
|
||
LED is ON
|
||
LED is OFF
|
||
...
|
||
```
|
||
|
||
**LED 状态：**
|
||
- LED 每秒切换一次亮灭状态
|
||
- 亮时对应高电平输出，灭时对应低电平输出
|
||
```
|
||
|
||
### 8. 核心 API（H2，强烈推荐）
|
||
|
||
**使用场景:**
|
||
|
||
- 设备驱动示例（Devices）
|
||
- 组件模块示例（Modules）
|
||
- 有明确 API 调用的示例
|
||
|
||
**格式:**
|
||
|
||
```markdown
|
||
## 核心 API
|
||
|
||
| API | 说明 |
|
||
|-----|------|
|
||
| `api_function_1()` | 功能说明1 |
|
||
| `api_function_2()` | 功能说明2 |
|
||
| `api_function_3()` | 功能说明3 |
|
||
```
|
||
|
||
**内容要求:**
|
||
|
||
1. **使用表格**: 固定两列格式
|
||
2. **API 名称**: 使用反引号 `包裹，保留括号 `()`
|
||
3. **顺序**: 按调用顺序排列
|
||
4. **数量**: 3-8 个关键 API
|
||
5. **说明**: 简洁准确，动词开头
|
||
|
||
**正确示例:**
|
||
|
||
```markdown
|
||
## 核心 API
|
||
|
||
| API | 说明 |
|
||
|-----|------|
|
||
| `lisa_device_get()` | 获取 GPIO 设备 |
|
||
| `lisa_device_ready()` | 检查设备是否就绪 |
|
||
| `lisa_gpio_configure()` | 配置 GPIO 引脚模式和属性 |
|
||
| `lisa_gpio_write_pin()` | 设置 GPIO 引脚输出电平 |
|
||
```
|
||
|
||
```markdown
|
||
## 核心 API
|
||
|
||
| API | 说明 |
|
||
|-----|------|
|
||
| `inram_malloc()` | 从内部 SRAM 分配内存 |
|
||
| `inram_free()` | 释放内部 SRAM 内存 |
|
||
| `psram_malloc()` | 从 PSRAM 分配内存 |
|
||
| `psram_calloc()` | 从 PSRAM 分配并清零内存 |
|
||
| `psram_realloc()` | 重新分配 PSRAM 内存 |
|
||
| `psram_free()` | 释放 PSRAM 内存 |
|
||
| `heap_summary_info()` | 打印堆统计信息 |
|
||
```
|
||
|
||
### 9. 关键代码（H2，强烈推荐）
|
||
|
||
**使用场景:**
|
||
|
||
- 有重要配置或技巧需要展示
|
||
- 代码包含关键 API 调用序列
|
||
- 需要解释复杂代码逻辑
|
||
|
||
**格式:**
|
||
|
||
```markdown
|
||
## 关键代码
|
||
|
||
```c
|
||
/* 注释说明 */
|
||
code_block();
|
||
|
||
/* 注释说明 */
|
||
another_code_block();
|
||
```
|
||
```
|
||
|
||
**内容要求:**
|
||
|
||
1. **语言标注**: 必须指定 `c`
|
||
2. **注释**: 关键代码添加中文注释
|
||
3. **完整性**: 代码片段可独立理解
|
||
4. **简洁性**: 省略无关代码，突出重点
|
||
|
||
**正确示例:**
|
||
|
||
```markdown
|
||
## 关键代码
|
||
|
||
```c
|
||
/* 配置为输出模式，初始电平为低 */
|
||
int ret = lisa_gpio_configure(gpio_dev, LED_PIN,
|
||
LISA_GPIO_OUTPUT | LISA_GPIO_OUTPUT_INIT_LOW);
|
||
|
||
/* 循环切换 LED 状态 */
|
||
bool led_on = true;
|
||
while (1) {
|
||
lisa_gpio_write_pin(gpio_dev, LED_PIN,
|
||
led_on ? LISA_GPIO_HIGH : LISA_GPIO_LOW);
|
||
LISA_LOGI(LOG_TAG, "LED is %s", led_on ? "ON" : "OFF");
|
||
vTaskDelay(pdMS_TO_TICKS(1000));
|
||
led_on = !led_on;
|
||
}
|
||
```
|
||
```
|
||
|
||
### 10. 配置说明（H2，可选）
|
||
|
||
**使用场景:**
|
||
|
||
- 有重要配置参数
|
||
- 配置有特殊要求或限制
|
||
- Kconfig 配置项说明
|
||
|
||
**格式:**
|
||
|
||
```markdown
|
||
## 配置说明
|
||
|
||
### 配置项1名称
|
||
|
||
{说明内容}
|
||
|
||
- **配置1**: 说明
|
||
- **配置2**: 说明
|
||
|
||
### 配置项2名称
|
||
|
||
{说明内容}
|
||
```
|
||
|
||
**正确示例:**
|
||
|
||
```markdown
|
||
## 配置说明
|
||
|
||
### 堆大小配置
|
||
|
||
在 Kconfig 中可配置堆大小（组件默认已配置）：
|
||
|
||
- **`CONFIG_HEAP_SIZE`**: 内部 SRAM 堆大小，默认 0x5000 (20KB)
|
||
- **`CONFIG_PSRAM_HEAP_SIZE`**: PSRAM 堆大小，默认 0x20000 (128KB)
|
||
|
||
### 对齐要求
|
||
|
||
- **`inram_malloc(align, size)`**: `align` 参数指定对齐字节数，必须是 2 的幂次方（4, 8, 16, 32 等）
|
||
- **`psram_malloc(size)`**: 默认 4 字节对齐
|
||
- **`psram_malloc_align(align, size)`**: 指定对齐字节数，用于 DMA 等需要特定对齐的场景
|
||
```
|
||
|
||
### 11. 注意事项（H2，强烈推荐）
|
||
|
||
**使用场景:**
|
||
|
||
- 所有示例都应包含
|
||
- 有重要限制或约束
|
||
- 常见错误提醒
|
||
|
||
**格式:**
|
||
|
||
```markdown
|
||
## 注意事项
|
||
|
||
1. **关键词1**: 详细说明
|
||
2. **关键词2**: 详细说明
|
||
3. **关键词3**: 详细说明
|
||
```
|
||
|
||
**内容要求:**
|
||
|
||
1. **使用有序列表**
|
||
2. **关键词粗体**: 每项开头用 **粗体** 标注关键词
|
||
3. **数量**: 3-5 项为宜
|
||
4. **内容**: 安全、限制、易错点、最佳实践
|
||
|
||
**正确示例:**
|
||
|
||
```markdown
|
||
## 注意事项
|
||
|
||
1. **返回值检查**: 分配内存后务必检查返回值是否为 NULL，防止使用无效指针
|
||
2. **内存释放**: 使用完毕后及时释放内存，避免内存泄漏
|
||
3. **对齐参数**: `align` 参数必须是 2 的幂次方，否则会导致对齐错误
|
||
4. **自动初始化**: 系统堆在 main 函数前自动初始化，无需手动调用
|
||
5. **线程安全**: 所有堆分配接口都是线程安全的，可在多任务环境下使用
|
||
```
|
||
|
||
---
|
||
|
||
## 不同类型示例的差异
|
||
|
||
### Devices（设备驱动示例）
|
||
|
||
**特征:**
|
||
|
||
- 使用 LISA 设备驱动 API
|
||
- 必需硬件连接说明
|
||
- 强调引脚配置和参数
|
||
|
||
**必需章节:**
|
||
|
||
- ✅ 硬件连接（详细引脚说明）
|
||
- ✅ 核心 API（LISA 设备 API）
|
||
- ✅ 注意事项（硬件相关限制）
|
||
|
||
**可选章节:**
|
||
|
||
- 配置说明（参数配置）
|
||
- 验证方法（硬件验证）
|
||
|
||
**示例:** [lisa_gpio/output_basic](samples/drivers/devices/lisa_gpio/output_basic/)
|
||
|
||
### Modules（组件模块示例）
|
||
|
||
**特征:**
|
||
|
||
- 系统组件/中间件
|
||
- 可能无硬件依赖
|
||
- 注重 API 使用方法
|
||
|
||
**必需章节:**
|
||
|
||
- ✅ 功能说明（详细功能说明）
|
||
- ✅ 核心 API（组件 API）
|
||
- ✅ 关键代码（使用示例）
|
||
|
||
**可选章节:**
|
||
|
||
- 配置说明（Kconfig 配置）
|
||
- 使用场景（应用场景）
|
||
|
||
**示例:** [modules/sys_heap](samples/modules/sys_heap/), [modules/lisa_shell](samples/modules/lisa_shell/)
|
||
|
||
### Network（网络示例）
|
||
|
||
**特征:**
|
||
|
||
- 涉及网络协议
|
||
- 需要环境配置
|
||
- 包含连接建立过程
|
||
|
||
**必需章节:**
|
||
|
||
- ✅ 功能说明（网络功能）
|
||
- ✅ 测试环境准备（环境配置）
|
||
- ✅ 预期输出（网络交互日志）
|
||
|
||
**可选章节:**
|
||
|
||
- 核心 API（网络 API）
|
||
- 配置说明（网络参数）
|
||
|
||
**示例:** [network/http](samples/network/http/)
|
||
|
||
### HAL（硬件抽象层示例）
|
||
|
||
**特征:**
|
||
|
||
- 底层硬件接口
|
||
- 使用表情符号标题（历史原因）
|
||
- 简洁实用
|
||
|
||
**必需章节:**
|
||
|
||
- ✅ 📖示例说明（功能说明）
|
||
- ✅ 硬件连接
|
||
- ✅ 预期输出
|
||
|
||
**特殊规则:**
|
||
|
||
- 可使用 `📖示例说明` 替代 `功能说明`
|
||
- 通常不包含核心 API 章节
|
||
|
||
---
|
||
|
||
## 格式规范
|
||
|
||
### 文档格式选择
|
||
|
||
#### Markdown 格式 (README.md) - 推荐
|
||
|
||
**优点:**
|
||
- 语法简洁，易于学习和编写
|
||
- GitHub/GitLab 原生支持预览
|
||
- 工具链完善
|
||
|
||
**适用场景:**
|
||
- 大部分示例文档
|
||
- 结构简单的文档
|
||
|
||
#### reStructuredText 格式 (README.rst) - 可选
|
||
|
||
**优点:**
|
||
- 功能强大，支持复杂文档结构
|
||
- Sphinx 文档系统原生格式
|
||
- 适合技术文档
|
||
|
||
**适用场景:**
|
||
- 需要复杂表格或指令的文档
|
||
- 需要与 Sphinx 文档系统集成
|
||
|
||
**选择建议:** 优先使用 Markdown，除非有特殊需求。
|
||
|
||
---
|
||
|
||
### Markdown 语法规范
|
||
|
||
#### 1. 标题层级
|
||
|
||
```markdown
|
||
# H1 - 文档标题（只能有一个）
|
||
## H2 - 主要章节
|
||
### H3 - 子章节
|
||
#### H4 - 更小的子章节（慎用）
|
||
```
|
||
|
||
**规则:**
|
||
|
||
- H1 只能有一个（文档标题）
|
||
- H2 用于主要章节
|
||
- H3 用于子章节（如"新特性"、配置项）
|
||
- 避免使用 H4 及以下层级
|
||
|
||
#### RST 等价语法
|
||
|
||
```rst
|
||
标题（H1）
|
||
=========
|
||
|
||
章节（H2）
|
||
---------
|
||
|
||
子章节（H3）
|
||
^^^^^^^^^^^
|
||
```
|
||
|
||
#### 2. 代码块
|
||
|
||
**Markdown 格式:**
|
||
|
||
```markdown
|
||
```c
|
||
// C 代码
|
||
```
|
||
|
||
```bash
|
||
# Bash 命令
|
||
```
|
||
|
||
```
|
||
纯文本输出
|
||
```
|
||
```
|
||
|
||
**RST 格式:**
|
||
|
||
```rst
|
||
.. code-block:: c
|
||
|
||
// C 代码
|
||
|
||
.. code-block:: bash
|
||
|
||
# Bash 命令
|
||
|
||
.. code-block:: text
|
||
|
||
纯文本输出
|
||
```
|
||
|
||
**语言标注要求:**
|
||
|
||
- `c`: C 语言代码
|
||
- `bash`: Shell 命令
|
||
- `text` (RST) 或无标注 (Markdown): 纯文本输出
|
||
|
||
#### 3. 行内代码标记
|
||
|
||
**Markdown 格式:**
|
||
|
||
```markdown
|
||
使用 `lisa_gpio_configure()` 配置引脚。
|
||
配置项 `CONFIG_HEAP_SIZE` 的默认值是 0x5000。
|
||
变量 `gpio_dev` 保存设备句柄。
|
||
```
|
||
|
||
**RST 格式:**
|
||
|
||
```rst
|
||
使用 ``lisa_gpio_configure()`` 配置引脚。
|
||
配置项 ``CONFIG_HEAP_SIZE`` 的默认值是 0x5000。
|
||
变量 ``gpio_dev`` 保存设备句柄。
|
||
```
|
||
|
||
**规则:**
|
||
|
||
- API 函数名保留括号: `function()` (Markdown) 或 ``function()`` (RST)
|
||
- 配置项宏定义: `CONFIG_NAME`
|
||
- 变量名: `variable_name`
|
||
|
||
#### 4. 粗体使用
|
||
|
||
**关键概念、重要信息:**
|
||
|
||
```markdown
|
||
- **返回值检查**: 务必检查返回值
|
||
- **内存对齐**: 必须 **32 字节对齐**
|
||
连接到 PC 串口工具，配置为 **115200, 8N1, 无流控**
|
||
```
|
||
|
||
**规则:**
|
||
|
||
- 注意事项的关键词
|
||
- 重要参数值
|
||
- 强调的概念
|
||
|
||
#### 5. 表格格式
|
||
|
||
**Markdown 格式:**
|
||
|
||
```markdown
|
||
| 列1标题 | 列2标题 |
|
||
|---------|---------|
|
||
| 内容1 | 说明1 |
|
||
| 内容2 | 说明2 |
|
||
```
|
||
|
||
**RST 格式:**
|
||
|
||
```rst
|
||
.. list-table::
|
||
:header-rows: 1
|
||
|
||
* - 列1标题
|
||
- 列2标题
|
||
* - 内容1
|
||
- 说明1
|
||
* - 内容2
|
||
- 说明2
|
||
```
|
||
|
||
**规则:**
|
||
|
||
- Markdown: 使用对齐的 `|` 分隔符，第二行用 `-` 分隔标题和内容
|
||
- RST: 使用 `.. list-table::` 指令，`:header-rows: 1` 指定标题行
|
||
- API 表格固定格式: `| API | 说明 |` (Markdown) 或对应的 RST list-table
|
||
|
||
#### 6. 列表格式
|
||
|
||
**有序列表（步骤、注意事项）:**
|
||
|
||
```markdown
|
||
1. 第一步
|
||
2. 第二步
|
||
3. 第三步
|
||
```
|
||
|
||
**无序列表（特性、引脚、配置）:**
|
||
|
||
```markdown
|
||
- 项目1
|
||
- 项目2
|
||
- 项目3
|
||
```
|
||
|
||
**子列表（2 空格缩进）:**
|
||
|
||
```markdown
|
||
- 父项目
|
||
- 子项目1
|
||
- 子项目2
|
||
```
|
||
|
||
### 语言规范
|
||
|
||
#### 1. 中英文使用规则
|
||
|
||
| 位置 | 语言 | 示例 |
|
||
|------|------|------|
|
||
| 文档正文 | 中文 | 演示如何使用... |
|
||
| 代码注释 | 中文 | `/* 配置引脚为输出模式 */` |
|
||
| API 名称 | 英文 | `lisa_gpio_configure()` |
|
||
| 配置项 | 英文 | `CONFIG_HEAP_SIZE` |
|
||
| 日志输出 | 英文 | `LISA_LOGI(LOG_TAG, "Device ready");` |
|
||
| 代码变量 | 英文 | `uint8_t *buffer;` |
|
||
|
||
#### 2. 术语标准表达
|
||
|
||
**模块名称:**
|
||
|
||
- ✅ LISA GPIO（正确）
|
||
- ❌ lisa_gpio, GPIO, lisa gpio（错误）
|
||
|
||
**技术术语:**
|
||
|
||
- ✅ DMA 模式（正确）
|
||
- ❌ dma 模式, Dma 模式（错误）
|
||
|
||
- ✅ 中断模式（正确）
|
||
- ❌ INT 模式, interrupt 模式（错误）
|
||
|
||
- ✅ 同步/异步（正确）
|
||
- ❌ sync/async（仅在代码中使用）
|
||
|
||
**一致性原则:**
|
||
|
||
同一概念在整篇文档中必须使用统一术语，不能混用。
|
||
|
||
#### 3. 中英文混排
|
||
|
||
**规则:**
|
||
|
||
中英文之间通常不加空格（除非是完整英文句子）。
|
||
|
||
**示例:**
|
||
|
||
```markdown
|
||
✅ 使用`lisa_gpio_configure()`配置引脚为输出模式。
|
||
✅ 使用 `lisa_gpio_configure()` 配置引脚为输出模式。
|
||
✅ 配置项`CONFIG_HEAP_SIZE`的默认值是 0x5000。
|
||
```
|
||
|
||
---
|
||
|
||
## AI 生成文档指南
|
||
|
||
### 生成流程
|
||
|
||
当 AI 收到"生成示例文档"的任务时，按以下流程操作：
|
||
|
||
#### 第一步：确定示例类型
|
||
|
||
```
|
||
问题：这是哪种类型的示例？
|
||
选项：
|
||
- Devices（设备驱动）
|
||
- Modules（组件模块）
|
||
- Network（网络示例）
|
||
- HAL（硬件抽象层）
|
||
```
|
||
|
||
#### 第二步：确定复杂度
|
||
|
||
```
|
||
问题：这是基础示例还是高级示例？
|
||
- 基础示例：使用基础模板，包含必需章节
|
||
- 高级示例：使用高级模板，增加"新特性"、"使用场景"等章节
|
||
```
|
||
|
||
#### 第三步：收集信息
|
||
|
||
```
|
||
收集以下信息：
|
||
1. 模块名称（如：LISA GPIO、系统堆管理）
|
||
2. 功能描述（如：基础输出、内存分配）
|
||
3. 硬件连接（引脚信息或"无需外部连接"）
|
||
4. 示例步骤（3-6 个关键步骤）
|
||
5. 核心 API（3-8 个关键 API 及说明）
|
||
6. 预期输出（实际日志或输出描述）
|
||
7. 注意事项（3-5 个关键限制或提醒）
|
||
```
|
||
|
||
#### 第四步：选择模板
|
||
|
||
根据类型和复杂度选择合适模板：
|
||
|
||
```
|
||
基础示例模板：
|
||
- 标题
|
||
- 功能说明
|
||
- 硬件连接
|
||
- 示例内容
|
||
- 编译（使用 RST 引用）
|
||
- 烧录（使用 RST 引用）
|
||
- 预期输出
|
||
- 核心 API
|
||
- 关键代码
|
||
- 注意事项
|
||
|
||
高级示例模板：
|
||
- 标题
|
||
- 功能说明
|
||
- 新特性（H3）
|
||
- 硬件连接
|
||
- 使用场景
|
||
- 示例步骤
|
||
- 编译（使用 RST 引用）
|
||
- 烧录（使用 RST 引用）
|
||
- 预期输出
|
||
- 核心 API
|
||
- 功能详解
|
||
- 关键代码
|
||
- 配置说明
|
||
- 注意事项
|
||
```
|
||
|
||
#### 第五步：填充内容
|
||
|
||
按模板顺序填充各章节，确保：
|
||
|
||
1. **标题格式正确**: `# {模块} {功能}示例`
|
||
2. **功能说明简洁**: 1-2 句话
|
||
3. **硬件连接完整**: 引脚信息或明确说明"无需外部连接"
|
||
4. **步骤清晰有序**: 使用有序列表
|
||
5. **编译和烧录**: 使用 RST 引用格式（`.. include:: /sample_build.rst` 和 `.. include:: /sample_flash.rst`）
|
||
6. **API 表格规范**: 使用标准表格格式
|
||
7. **代码块标注语言**: `c`、`bash` 或无标注
|
||
8. **注意事项完整**: 3-5 项，关键词粗体
|
||
|
||
#### 第六步：自检
|
||
|
||
生成后对照"AI 审查文档清单"自检。
|
||
|
||
### 生成示例模板
|
||
|
||
#### 基础示例模板
|
||
|
||
```markdown
|
||
# {模块名称} {功能描述}示例
|
||
|
||
## 功能说明
|
||
|
||
{1-2 句话说明核心功能}
|
||
|
||
## 硬件连接
|
||
|
||
- **引脚1**: 功能说明
|
||
- **引脚2**: 功能说明
|
||
|
||
或：
|
||
|
||
无需外部连接，{模块}为芯片内部资源。
|
||
|
||
## 示例内容
|
||
|
||
1. 步骤1
|
||
2. 步骤2
|
||
3. 步骤3
|
||
4. 步骤4
|
||
|
||
## 编译
|
||
|
||
```{eval-rst}
|
||
.. include:: /sample_build.rst
|
||
```
|
||
|
||
## 烧录
|
||
|
||
```{eval-rst}
|
||
.. include:: /sample_flash.rst
|
||
```
|
||
|
||
## 预期输出
|
||
|
||
```
|
||
[I][sample] === Example Output ===
|
||
{实际输出内容}
|
||
```
|
||
|
||
## 核心 API
|
||
|
||
| API | 说明 |
|
||
|-----|------|
|
||
| `api_1()` | 功能说明1 |
|
||
| `api_2()` | 功能说明2 |
|
||
| `api_3()` | 功能说明3 |
|
||
|
||
## 关键代码
|
||
|
||
```c
|
||
/* 关键代码片段 */
|
||
code_example();
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **关键词1**: 说明
|
||
2. **关键词2**: 说明
|
||
3. **关键词3**: 说明
|
||
```
|
||
|
||
#### 高级示例模板
|
||
|
||
```markdown
|
||
# {模块名称} {功能描述}示例（{模式说明}）
|
||
|
||
## 功能说明
|
||
|
||
{1-2 句话说明核心功能}
|
||
|
||
### 新特性
|
||
|
||
- **特性1**: 说明
|
||
- **特性2**: 说明
|
||
- **特性3**: 说明
|
||
|
||
## 硬件连接
|
||
|
||
- **引脚1**: 功能说明
|
||
- **引脚2**: 功能说明
|
||
|
||
{补充连接说明}
|
||
|
||
## 使用场景
|
||
|
||
{适用场景和技术选型说明}
|
||
|
||
## 示例步骤
|
||
|
||
1. 步骤1
|
||
2. 步骤2
|
||
3. 步骤3
|
||
4. 步骤4
|
||
|
||
## 编译
|
||
|
||
```{eval-rst}
|
||
.. include:: /sample_build.rst
|
||
```
|
||
|
||
## 烧录
|
||
|
||
```{eval-rst}
|
||
.. include:: /sample_flash.rst
|
||
```
|
||
|
||
## 预期输出
|
||
|
||
**终端输出：**
|
||
```
|
||
[I][sample] === Example Output ===
|
||
{输出内容}
|
||
```
|
||
|
||
**{其他输出源}：**
|
||
{描述}
|
||
|
||
## 核心 API
|
||
|
||
| API | 说明 |
|
||
|-----|------|
|
||
| `api_1()` | 功能说明1 |
|
||
| `api_2()` | 功能说明2 |
|
||
| `api_3()` | 功能说明3 |
|
||
|
||
## {功能}说明
|
||
|
||
{详细说明工作原理和特性}
|
||
|
||
## 关键代码
|
||
|
||
```c
|
||
/* 关键代码片段 */
|
||
code_example();
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
### 配置项1
|
||
|
||
{说明}
|
||
|
||
### 配置项2
|
||
|
||
{说明}
|
||
|
||
## 注意事项
|
||
|
||
1. **关键词1**: 说明
|
||
2. **关键词2**: 说明
|
||
3. **关键词3**: 说明
|
||
4. **关键词4**: 说明
|
||
```
|
||
|
||
---
|
||
|
||
## AI 审查文档清单
|
||
|
||
当 AI 收到"检查示例文档"的任务时，使用以下清单逐项检查：
|
||
|
||
### 结构检查
|
||
|
||
```
|
||
□ 标题（H1）存在且格式正确
|
||
□ 功能说明（H2）存在且简洁（1-2 句话，40-200 字）
|
||
□ 硬件连接（H2）存在且完整（有引脚信息或明确说明无需连接）
|
||
□ 示例内容/步骤（H2）存在且使用有序列表
|
||
□ 编译（H2）存在且使用 RST 引用（推荐）或包含构建命令
|
||
□ 烧录（H2）存在且使用 RST 引用（推荐）或包含烧录命令
|
||
□ 预期输出（H2）存在且非空
|
||
□ 核心 API（H2）存在（Devices/Modules 类型）
|
||
□ 注意事项（H2）存在且有 3-5 项
|
||
□ 章节顺序符合规范
|
||
```
|
||
|
||
### 格式检查
|
||
|
||
```
|
||
□ 文档格式正确（Markdown .md 或 RST .rst）
|
||
□ 所有代码块指定了语言（c/bash/text）
|
||
□ 编译和烧录使用引用格式（Markdown 用 eval-rst，RST 用 include 指令）
|
||
□ API 名称使用正确标记（Markdown 用 `，RST 用 ``）
|
||
□ 核心 API 使用标准表格格式（Markdown 表格或 RST list-table）
|
||
□ 注意事项使用有序列表，关键词用粗体（Markdown **粗体**，RST **粗体**）
|
||
□ 引脚编号用粗体（Markdown **PB09**，RST **PB09**）
|
||
□ 中英文混排符合规范
|
||
□ 无过深层级标题（避免 H4/H5 或 RST 过多下划线层级）
|
||
□ 编译和烧录为独立章节（不使用子章节）
|
||
□ 格式内部保持一致（不混用 Markdown 和 RST 语法）
|
||
```
|
||
|
||
### 内容检查
|
||
|
||
```
|
||
□ 标题格式：{模块} {功能}示例
|
||
□ 功能说明不超过 200 字
|
||
□ 硬件连接有具体引脚或明确说明无需连接
|
||
□ 示例步骤有 3-6 项
|
||
□ 预期输出与代码一致（如果有源代码）
|
||
□ API 表格有 3-8 项，按调用顺序排列
|
||
□ 注意事项包含重要限制和易错点
|
||
□ 术语使用一致（如：DMA 模式，不是 dma 模式）
|
||
```
|
||
|
||
### 语言检查
|
||
|
||
```
|
||
□ 文档正文使用中文
|
||
□ API 名称使用英文
|
||
□ 代码注释使用中文
|
||
□ 日志输出使用英文
|
||
□ 术语表达标准化（LISA GPIO、DMA 模式、中断模式）
|
||
□ 同一概念术语统一，无混用
|
||
```
|
||
|
||
### 类型特定检查
|
||
|
||
**Devices（设备驱动）:**
|
||
|
||
```
|
||
□ 标题使用 LISA 前缀（如：LISA GPIO）
|
||
□ 硬件连接详细（引脚编号、功能、接线方式）
|
||
□ 核心 API 包含 lisa_device_get() 等设备 API
|
||
□ 注意事项包含硬件相关限制
|
||
```
|
||
|
||
**Modules（组件模块）:**
|
||
|
||
```
|
||
□ 功能说明详细说明组件功能
|
||
□ 硬件连接说明"无需外部连接"（如适用）
|
||
□ 核心 API 包含组件关键 API
|
||
□ 可选：配置说明章节（Kconfig）
|
||
```
|
||
|
||
**Network（网络示例）:**
|
||
|
||
```
|
||
□ 功能说明包含网络协议/功能
|
||
□ 可选：测试环境准备章节
|
||
□ 预期输出包含网络交互日志
|
||
□ 注意事项包含网络环境要求
|
||
```
|
||
|
||
### 审查报告格式
|
||
|
||
AI 检查后应输出以下格式的报告：
|
||
|
||
```markdown
|
||
# 文档审查报告
|
||
|
||
**文档路径**: {文件路径}
|
||
**示例类型**: {Devices/Modules/Network/HAL}
|
||
**审查日期**: {日期}
|
||
|
||
## 审查结果
|
||
|
||
**总体评分**: {通过/需修改/不合格}
|
||
|
||
## 问题清单
|
||
|
||
### 必需修改（阻塞问题）
|
||
|
||
1. **[结构]** {问题描述}
|
||
- **位置**: {章节名称}
|
||
- **问题**: {具体问题}
|
||
- **建议**: {修改建议}
|
||
|
||
2. **[格式]** {问题描述}
|
||
- **位置**: {章节名称/行号}
|
||
- **问题**: {具体问题}
|
||
- **建议**: {修改建议}
|
||
|
||
### 建议优化（非阻塞）
|
||
|
||
1. **[内容]** {问题描述}
|
||
- **位置**: {章节名称}
|
||
- **建议**: {优化建议}
|
||
|
||
## 符合规范项
|
||
|
||
✅ 标题格式正确
|
||
✅ 功能说明简洁
|
||
✅ 章节顺序符合规范
|
||
...
|
||
|
||
## 总结
|
||
|
||
{总体评价和建议}
|
||
```
|
||
|
||
---
|
||
|
||
## 附录
|
||
|
||
### 附录 A：常见问题
|
||
|
||
#### Q1: 何时使用"示例内容"vs"示例步骤"？
|
||
|
||
**A**:
|
||
- **示例内容**: 用于功能演示类示例，列出演示的功能点
|
||
- **示例步骤**: 用于操作流程类示例，列出执行的步骤
|
||
|
||
示例：
|
||
```markdown
|
||
## 示例内容（功能演示）
|
||
1. 从内部 SRAM 分配内存
|
||
2. 从外部 PSRAM 分配内存
|
||
3. 使用 calloc 分配并清零内存
|
||
|
||
## 示例步骤（操作流程）
|
||
1. 获取 UART 设备
|
||
2. 配置 UART 参数
|
||
3. 发送数据并等待完成
|
||
```
|
||
|
||
#### Q2: 何时添加"新特性"章节？
|
||
|
||
**A**:
|
||
- 高级示例（DMA、中断、异步等）
|
||
- 有明显技术优势需要突出
|
||
- 与基础示例有显著差异
|
||
|
||
#### Q3: 硬件连接章节可以省略吗？
|
||
|
||
**A**:
|
||
不可以。所有示例都必须包含硬件连接章节，即使无需外部连接，也应明确说明"无需外部连接，{模块}为芯片内部资源"。
|
||
|
||
#### Q4: 预期输出必须包含实际日志吗？
|
||
|
||
**A**:
|
||
是的。预期输出必须与实际运行结果一致。如果输出很长，可以使用 `...` 省略重复部分，但关键日志必须包含。
|
||
|
||
#### Q5: 核心 API 章节是必需的吗？
|
||
|
||
**A**:
|
||
强烈推荐，特别是 Devices 和 Modules 类型示例。Network 和 HAL 类型可根据情况选择。
|
||
|
||
### 附录 B：术语对照表
|
||
|
||
| 中文术语 | 英文术语 | 使用场景 |
|
||
|----------|----------|----------|
|
||
| 设备驱动 | Device Driver | 文档正文 |
|
||
| 组件模块 | Module | 文档正文 |
|
||
| 引脚 | Pin | 硬件连接 |
|
||
| 中断模式 | Interrupt Mode | 功能说明 |
|
||
| DMA 模式 | DMA Mode | 功能说明 |
|
||
| 同步发送 | Synchronous Send | 功能说明 |
|
||
| 异步发送 | Asynchronous Send | 功能说明 |
|
||
| 循环缓冲区 | Circular Buffer | 技术说明 |
|
||
| 串口工具 | Serial Tool | 硬件连接 |
|
||
| 波特率 | Baud Rate | 配置说明 |
|
||
| 占空比 | Duty Cycle | PWM 相关 |
|
||
| 内存对齐 | Memory Alignment | 配置说明 |
|
||
|
||
### 附录 C：Markdown 与 RST 格式对照
|
||
|
||
#### 基本语法对照表
|
||
|
||
| 元素 | Markdown | RST |
|
||
|------|----------|-----|
|
||
| H1 标题 | `# 标题` | `标题\n====` |
|
||
| H2 标题 | `## 标题` | `标题\n----` |
|
||
| H3 标题 | `### 标题` | `标题\n^^^^` |
|
||
| 行内代码 | `` `code` `` | ``` ``code`` ``` |
|
||
| 代码块 | ` ```c\ncode\n``` ` | `.. code-block:: c\n\n code` |
|
||
| 粗体 | `**粗体**` | `**粗体**` |
|
||
| 链接 | `[text](url)` | `` `text <url>`_ `` |
|
||
| 表格 | Markdown table | `.. list-table::` |
|
||
| Include | `{eval-rst}\n.. include::` | `.. include::` |
|
||
|
||
#### 完整示例对照
|
||
|
||
**Markdown 版本:**
|
||
```markdown
|
||
# LISA GPIO 基础输出示例
|
||
|
||
## 功能说明
|
||
|
||
演示如何使用 `lisa_gpio_configure()` 配置引脚。
|
||
|
||
## 编译
|
||
|
||
```{eval-rst}
|
||
.. include:: /sample_build.rst
|
||
```
|
||
|
||
## 核心 API
|
||
|
||
| API | 说明 |
|
||
|-----|------|
|
||
| `lisa_device_get()` | 获取设备 |
|
||
```
|
||
|
||
**RST 版本:**
|
||
```rst
|
||
LISA GPIO 基础输出示例
|
||
======================
|
||
|
||
功能说明
|
||
--------
|
||
|
||
演示如何使用 ``lisa_gpio_configure()`` 配置引脚。
|
||
|
||
.. include:: /sample_build.rst
|
||
|
||
核心 API
|
||
--------
|
||
|
||
.. list-table::
|
||
:header-rows: 1
|
||
|
||
* - API
|
||
- 说明
|
||
* - ``lisa_device_get()``
|
||
- 获取设备
|
||
```
|
||
|
||
### 附录 D：示例文档索引
|
||
|
||
**优秀示例文档（推荐参考）:**
|
||
|
||
- **Devices (Markdown)**:
|
||
- [samples/drivers/devices/lisa_gpio/output_basic/README.md](samples/drivers/devices/lisa_gpio/output_basic/README.md)
|
||
- [samples/drivers/devices/lisa_uart/send_async_dma/README.md](samples/drivers/devices/lisa_uart/send_async_dma/README.md)
|
||
|
||
- **Modules (Markdown)**:
|
||
- [samples/modules/sys_heap/README.md](samples/modules/sys_heap/README.md)
|
||
- [samples/modules/lisa_shell/README.md](samples/modules/lisa_shell/README.md)
|
||
|
||
- **Network (Markdown)**:
|
||
- [samples/network/http/README.md](samples/network/http/README.md)
|
||
|
||
- **Basic (RST)**:
|
||
- [samples/helloworld/README.rst](samples/helloworld/README.rst)
|
||
|
||
### 附录 E：版本历史
|
||
|
||
| 版本 | 日期 | 变更说明 |
|
||
|------|------|----------|
|
||
| 1.0 | 2025-01-15 | 初始版本（Samples_Spec.md） |
|
||
| 2.0 | 2025-01-14 | AI 辅助版，基于 114 个示例文档分析 |
|
||
| 2.1 | 2025-01-14 | 支持 Markdown 和 RST 两种格式 |
|
||
|
||
**主要变更（2.1）:**
|
||
|
||
1. **支持双格式**: 允许使用 Markdown (.md) 或 reStructuredText (.rst)
|
||
2. **格式对照**: 新增附录 C - Markdown 与 RST 格式对照表
|
||
3. **审查清单更新**: 格式检查项适配双格式要求
|
||
4. **语法规范**: 补充 RST 格式的等价语法说明
|
||
5. **示例索引**: 新增 RST 格式示例文档引用
|
||
|
||
**主要变更（2.0）:**
|
||
|
||
1. 基于实际分析数据（114 个 README.md）
|
||
2. 明确不同类型示例的差异和特殊规则
|
||
3. 新增 AI 生成文档指南
|
||
4. 新增 AI 审查文档清单
|
||
5. 详细格式规范和示例
|
||
6. 新增常见问题和术语对照表
|
||
|
||
---
|
||
|
||
**维护者**: ARCS SDK 团队
|
||
**联系方式**: sdk@listenai.com
|
||
**最后更新**: 2025-01-14
|