应用笔记与 Wiki 编写规范

应用笔记与 Wiki 文档均为与 ARCS 相关的应用或说明文档，区别：

应用笔记可对社会公开；
Wiki 文档仅为公司内部人员开放，请勿外泄资源。

1 命名规则

1.1 文件夹命名规则

文档序号
- 为固定格式
文档英文名称，只包含数字、下划线“_”、折线“-”、小写英文字母

注意：文件夹名称中不可包含中文、空格、大写英文字母！

1.2 图片、附件等文件命名规则

图片、附件须重命名，命名格式 “（序号-）图片描述”
1. 图片的名称尽量描述图片内容，不要使用拼音
图片保存格式建议为 png 或 jpg，上传仓库前请先进行图片压缩处理

注意：文件名称、后缀中不可包中文、含空格、大写英文字母！

2 文档提交注意事项

2.1 Conventional Commits 提交规范

应用笔记、Wiki 文档提交时，commit 提交格式遵循 Conventional 提交规范。文档的新增或内容的变更等同软件研发新增或变更功能，常用 commit 类别有：

feat：新增文档或章节
fix：已有文档的变更
docs：变更说明文件、文件格式（不影响笔记/Wiki 文档内容）
style：样式

示例：

feat: 新增XX文档

fix: XX文档变更YY小节

docs: 更新文档编写说明

style: 优化XX文档的格式

更多 Conventional 提交规范请参见《Conventional 提交规范》。

2.2 更新目录文件

每次新增文档，请在文档正文顶部增加模板源数据区、更新 SUMMARY.md 文件，注意文章的序号、标题保持一致。

3 应用笔记文件管理

仓库目录结构

application_notes                         # 根目录
│
├─ zh                                     # 中文应用笔记
│   ├── 01-note1                          # note1 示例（存放 note1 文档及文档中的图片）
│   ├── index.md                          # 存放 note1 文档内容                   
│   └── pics                              # 存放 note1 文档中需要的图片
│       ├── 1.png
│       ├── 2.png
│       └── ...
│
├─ en                                     # 英文应用笔记
│   ├── 01-note1                          # note1 示例（存放 note1 文档及文档中的图片）
│   ├── index.md                          # 存放 note1 文档内容                   
│   └── pics                              # 存放 note1 文档中需要的图片
│       ├── 1.png
│       ├── 2.png
│       └── ...
│
├── public                                # 公共资源              
│   └── files_application                 # 存放应用笔记文档中需要用户下载的附件
│       ├── 01-note1
│       │   └── file1                     # note1 的附件
│       ├── 02-note1 
│       │   └── file2                     # note2 的附件
│       └── ...
└── ...

3.1 附件上传

在 /public/files_application/ 文件夹中创建与对应应用笔记相同名称的文件夹，将附件文件上传至该文件夹中。

以 70-camera_use 为例：

打开 book 中的 index.md 文件，在需要引用附件的位置添加 <a> 标签即可。

<a href="/files_application/[目标文件夹名称]/[目标文件名称]" target="_blank">[附件名称]</a>

示例：
在文档中引用附件链接示例

4 Wiki 文件管理

仓库目录结构：

ARCS Wiki                                 # 根目录
│
├── book                                  # 存放 Wiki 文档及文档中的图片
│   ├── 01-Wiki01                         # Wiki 文档示例
│   │   ├── index.md                      # 存放 Wiki01 文档内容
│   │   └── pics                          # 存放 Wiki01 文档中需要的图片
│   │       ├── 1.png
│   │       ├── 2.png
│   │       └── ...
│   └── ...
│
└── files                                 # 存放 Wiki 文档中需要的附件
    ├── 01-Wiki01                         # 存放 Wiki01 文档的附件（文件夹名与 `book` 下的文件夹名保持一致）
    │   ├── annex-01-v1.0.0.xlsx          # 附件可以为 `.xlsx`、`.pro`、`.lua`、`.zip` 等格式的文件。
    │   ├── annex-02-v1.1.0.pro           # 须做好文件的版本更新记录
    │   ├── annex-03-v1.0.1.lua
    │   ├── annex-04-v2.0.0.zip
    │   └── ...
    └── ...

注意：应用笔记、Wiki 内所有存储文件名称为 index.md。

4.1 附件上传

在 files 文件夹中创建与 book 中相同名称的文件夹，将附件文件上传至该文件夹中。

以 11-friction_model_import 为例：