文档规范

文档使用 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 分支, 等构建完毕访问网址即可看到效果。