文档贡献规范

编辑本页

有几种情况你可能需要看本文档：

发现文档有误或者有内容需要补充，并且会自己想参与修改
提交教程/经验/开源项目分享等等

为了让文档看起来风格统一，内容不重复不出错，编写需要遵循同一个规范，请各位贡献者务必根据本文撰写文档；
如果对模板格式，内容存在疑惑请到本项目仓库 MaixPy_DOC 提交 ISSUE。

🙇‍ 感谢各位贡献者的热心支持！

要参与贡献，你需要提前掌握的知识

git 和 github 的使用
github PR（pull request）的使用

在入门教程里面有简要的介绍，详细的使用方法请自行学习

如果你没有信心掌握这些技能，你可以到提交issue 来说明问题或者贡献经验等，我们帮助你进行添加

文档系统简介

文档使用 gitbook 进行构建，并使用简单高效的 Markdown 编写内容, 这里推荐使用 Typora 或者 VS Code 搭配 MarkDown Preview Enhanced 插件作为文档编辑器

文档源码托管在 github

本地预览方法见文档源码的 README.md

文档有两种语言，中文和英文，分别放在zh和en文件夹中，其中的SUMMARY.md是文档左边的目录项，其它md文件时具体的文档文件，根目录下的assets目录放两种语言公用的图片资源文件

Markdown 语法

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

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

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

## 这是二级标题

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

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

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

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

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

                ( 至少需要一个以上的空行，建议2行 )

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

正文

## 二级标题2

正文

标题编号

所有标题不需要写编号， 会自动生成比如

## 标题一

### 子标题1

## 标题二

最终效果：

1. 标题一
  1.1 子标题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)

中英文混写

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

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

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

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

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

多种语言分别放在不同的目录，en和zh目录
生成的文档目录在对应语言的文件夹 SUMMARY.md 中编辑
源文档的文件夹尽量一个功能模块对应一个文件夹，资源文件（图片）放置到对应 md 文档根目录下的 assets 文件夹目录下，这样方便中英文文档都引用同样的图片，而且生成的 URL 相同，同时增删修改时更方便。
同时，为了中英文文档都能使用，图片里面尽量不要标注中文或英文，可以标注标号，然后文档用标号阐述，针对特定语言的图片放到当前路径下的 assets 目录：

assets/                                 (放公用的资源文件， 中英文都能引用)
en/
   |
   ----- get_started/
                  |
                  ---- assets/          (放get_started目录下md文件的资源文件， 只给英文使用)
                  |
                  ---- get_hardware.md
                  |
                  ---- how_to_read.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 分支，等构建完毕访问网址即可看到效果。

打包文件系统

代码编写规范

wiki