文档规范

2022-07-06

文档使用 gitbook 进行构建， 并使用简单高效的 Markdown 编写内容

文档源码托管在 GitHub

Markdown 语法

Markdown 的基础语法如果没接触过， 请花半个小时进行学习， 推荐github的教程： github Markdown 教程

在本文中， 以下几点我们需要注意：

标题类的语法标记必须使用空格隔开，大标题与正文之间需要一个空行，比如：

## 这是二级标题

* 这是列表项1
* 这是列表项2

而如下所示的则不是正确的，可能会导致解析器出现解析错误格式错乱等

##这是二级标题
*这是列表项1
*这是列表项2

所有页面只有一个一级标题

由于需要自动生成目录，主要是为了保证自动生成的目录正确。
每个页面这样写

页面标题/一级标题
=======         (这里等号至少需要三个)
                ( 至少需要一个以上的空行，建议2行 )

## 二级标题1     ( 这里不能使用一级标题，及不能用一个#号。 也不需要写序号，会自动生成序号)
                ( 空一行 )
正文
                ( 至少空一行)
### 三级标题      ( 类似二级标题, 也不需要写需要，会自动生成)

正文

## 二级标题2

正文

链接

由于页面众多，而且需要链接图片等资源，在写链接时，均使用相对路径，
比如目录结构如下

assets/                                 (放公用的资源文件)
      |
      ----pic000.png
en/
   |
   ----- get_started/
                  |
                  ---- assets/          (放get_started目录下md文件公用的资源文件)
                             |
                             ------ pic.png
                  |
                  ---- get_hardware.md
                  |
                  ---- how_to_read.md
zh/

如果在get_hardware.md中贴图片，将图片放进assets文件夹后，使用如下代码引用图片

![pic](assets/pic.png)
![pic](../../assets/pic000.png)

中英文混写

在写中文文档时，在中文中夹杂英文尽量用空格隔开，标点符号尽量使用全角符号，
主要是为了显眼，让文档更优雅。
比如如下对比：

The `setup` function is called when a sketch starts. Use it to initialize variables, pin modes, start using libraries, etc.

The setup function is called when a sketch starts. Use it to initialize variables, pin modes, start using libraries, etc.

The setup function is called when a sketch starts. Use it to initialize variables, pin modes, start using libraries, etc.

The setup function is called when a sketch starts. Use it to initialize variables, pin modes, start using libraries, etc.

目录和文件名

  • 生成的文档目录在对应语言的文件夹SUMMARY.md中编辑

  • 源文档的文件夹尽量一个功能模块对应一个文件夹，资源文件（图片）放置到对应 md 文档的当前路径的 assets文件夹目录下，这样在增删修改时更方便

assets/                                 (放公用的资源文件)
en/
   |
   ----- get_started/
                  |
                  ---- assets/          (放get_started目录下md文件公用的资源文件)
                  |
                  ---- get_hardware.md
zh/
  • 文件名除了README.md特殊，其它文件名使用 小写+下划线 的命名方式，比如 get_hardware.md

中英文（多语言）的页面文件目录结构和文件名相同

由于最后生成的页面中有多语言切换选项，点击切换后会直接访问对应语言的相同路径，所以中英文的目录结构和文件名必须相同。

比如英文正在访问en/get_started/how_to_read.md， 点击语言切换的按钮后，会自动访问zh/get_started/how_to_read.md， 如果这个文件不存在就会报404错误！

目录和链接

尽量引导阅读者使用目录，文内跳转链接慎用，如果链接跳得比较乱，会导致文档看起来比较乱，阅读会比较困难。

模块文档内容

  • 需要在文件头部包含模块的介绍
  • 需要分点说明构造函数、函数、常量等
  • 说明不能偷懒只简单将函数名称翻译一遍，需要详细说明函数的功能、参数的取值范围以及注意点

多版本管理

文档除了做了中英文（多语言）支持（不是自动翻译，需要手动修改）， 也做了多版本管理。

每个版本是一个分支， 对分支名字有要求， 分别为：

  • master 分支为主分支
  • dev分支为开发分支
  • 其它的发布的历史版本均以小写 v 开头，比如创建一个分支叫 v1.2

创建好新的分支后，需要在每个语言版本的目录下 book.json中修改版本链接，不然读者找不到入口

可以在新建的分支下本地预览（预览方法见根目录 README.md）， 注意这时候预览的页面就是当前分支的内容，如果要本地预览其它分支内容，需要先切换到其它分之后再预览即可。

确认无误修改完成后推送分支到远程（github）， 自动构建系统会自动构建并发布到 pages 分支， 等构建完毕访问网址即可看到效果。