文档贡献规范

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

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

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

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

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

    • git 和 github 的使用
    • github PR(pull request)的使用

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

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

    文档系统简介

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

    文档源码托管在 github

    本地预览方法见 文档源码的 index.html

    文档有两种语言, 中文和英文,分别放在zhen文件夹中, 其中的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 一样来表示设置默认值


    目录

    • 多种语言分别放在不同的目录,enzh目录

    • 生成的文档目录在对应语言的文件夹 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 分支,等构建完毕访问网址即可看到效果。