文档规范

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

文档源码托管在 github

1. Markdown 语法

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

在本文中, 以下几点我们需要注意:

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

## 这是二级标题

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

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

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

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

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

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

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

正文

## 二级标题2

正文

1.3. 链接

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

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)

1.4. 中英文混写

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


在 Micropython 中, 我们常常使用`deinit`来表示析构函数,而不是像 STM32 一样来表示设置默认值

在 Micropython 中, 我们常常使用deinit来表示析构函数,而不是像 STM32 一样来表示设置默认值


在Micropython中, 我们常常使用deinit来表示析构函数,而不是像STM32一样来表示设置默认值

在Micropython中, 我们常常使用deinit来表示析构函数,而不是像STM32一样来表示设置默认值


2. 目录和文件名

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

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

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

3. 中英文(多语言)的页面文件目录结构和文件名相同

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

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

4. 模块文档内容

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

results matching ""

    No results matching ""