[野火]sphinx文档规范与模版

关于本项目

本项目的github地址：https://github.com/Embdefire/ebf_contribute_guide

本项目的gitee 地址：https://gitee.com/wildfireteam/ebf_contribute_guide

点击右侧链接可在线阅读本项目文档：《 [野火]sphinx文档规范与模版 》

本文档是关于如何使用sphinx编写文档的说明。 也可以把本文档作为模版创建其它sphinx的文档。

为什么使用sphinx编写文档

使用shpinx编写文档有如下优点：

• 使用sphinx编写的文档可以方便地制作html、pdf等格式，非常方便浏览和转换。
• sphinx支持rst和markdown语法，方便共享及开源编辑，使用git也方便跟踪。
• 由于rst语法比markdown语法更强大和方便，我们主要采用rst语法编写文档， linux内核源码文档也是使用rst格式编写的。 我们的文档也支持markdown，主要是为了方便不熟悉rst的用户参与进来。

关于野火

开源共享，共同进步

野火在发布第一块STM32开发板之初，就喊出 开源共享，共同进步 的口号， 把代码和文档教程都免费提供给用户下载，而我们也一直把这个理念贯穿至今。

目前我们的产品已经包括 STM32、i.MX RT系列、GD32V、FPGA、Linux、emXGUI、 操作系统、网络、下载器 等分支，覆盖电子工程应用领域的各种常用技术， 其中教学类产品的代码和文档一直保持着开源的姿态发布到网络上， 为电子工程师排忧解难，让嵌入式没有难用的技术是我们最大的愿望。

联系方式

• 官网： http://www.embedfire.com
• 论坛： http://www.firebbs.cn
• github主页：https://github.com/Embedfire
• gitee主页： https://gitee.com/wildfireteam
• 淘宝： https://yehuosm.tmall.com
• 邮箱： embedfire@embedfire.com
• 电话： 0769-33894118

快速参与本项目（提交bug或文档修改）

开源代码和文档最重要的初衷是让大家参与进来，一起来找茬。

无论你是觉得代码写得不够漂亮、有bug，或是文档小到有错别字，大到有原理性的描述错误， 都可以直接通过项目的github提交给我们，我们会视具体的情况进行审核处理加入到主线或特性分支。

野火的每个项目的《 关于本项目 》文件中都包含有项目的git仓库地址， 通过git提交 issue 、pull request 的方式可参与到项目。

我们主要使用github仓库进行维护和更新，gitee仓库用于方便用户快速下载， 我们一般只在gitee上同步github的master分支，所以参与项目时请尽量使用github。

轻度参与，提交issue

如果你发现了一些bug或小问题，而自己暂时没时间帮助我们修改的话， 可以直接在项目的github中提交issue告诉我们，我们会适时进行处理。

深度参与，提交pull request

如果你想深度参与本项目，可以先克隆或fork项目的仓库到本地， 修改编辑后向我们提交pull request，我们会审核处理。

TODO和悬赏任务

本页记录待改进的事项，以后会在此页发布任务清单，完成部分任务可获得 奖励 ，敬请期待！

如果您想参与到项目，可按《 快速参与本项目（提交bug或文档修改） 》的说明操作。

文档任务

此处写具体的任务列表

• PDF与readthedocs
• 详细写如何贡献（git issue和commit）

代码开发任务

此处写具体的任务列表

sphinx的安装与使用

安装sphinx

sphinx官方安装说明： http://www.sphinx-doc.org/en/master/usage/installation.html

readthedoc官方说明： https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html

总的来说步骤如下：

• 安装python3
• 通过python3安装sphinx包
• 根据项目要求安装项目的requirements.txt里的软件包

安装python3

windows直接到python官网下载安装

Ubuntu下使用如下指令安装：

sudo apt install python3

安装sphinx

windows下使用如下指令安装：

py -3 -m pip install sphinx
#国内用户推荐使用清华源安装，使用-i指定源
py -3 -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx

Ubuntu下使用如下指令安装

python3 -m pip install sphinx
#国内用户推荐使用清华源安装，使用-i指定源
python3 -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx

#Ubuntu下可能还需要安装如下软件包
apt-get install python3-sphinx

使用模板创建sphinx文档

本项目的sphinx已适配好支持markdown、默认的readthedoc主题等内容。

如果是要编写新的书籍，推荐直接使用本项目文档作为模版，修改conf.py文件的配置即可改变项目的名字、主题之类的内容。

下载项目源码

先从github下载本项目源代码：

git clone git@github.com:Embdefire/ebf_contribute_guide.git

下载完成后，可看到本项目的结构大致如下：

├── README                    说明文档或软链接至documentation中的说明，方便github阅读
├── base_code                 配套代码
└── documentation             配套文档
    ├── faq                   存储常见问题的文档
    ├── about_us.rst          关于我们
    ├── _build                文档编译输出目录
    ├── conf.py               sphinx配置文件
    ├── contribute            如何参与项目，贡献与投稿的说明
    ├── foreword.rst          前言
    ├── index.rst             目录
    ├── make.bat
    ├── Makefile
    ├── media                 文档中使用的图片文件
    ├── requirements.txt      文档的python依赖
    ├── _static
    ├── _templates
    ├── TODO.rst              待完成的内容，发布的任务列表

特别内容说明如下：

• base_code ：该目录通常存放项目的代码，
• documentation ：该目录通常存放项目的文档内容，如我们的rst、markdown文档。

安装python依赖包

使用时，要先根据项目的 documentation/requirements.txt 安装依赖的python包。

#切换至requirements.txt文件的同级目录
cd documentation

#requirements.txt文件的同级目录下执行后面的命令

#Windows指令，推荐使用powershell运行
py -3 -m pip install -r requirements.txt
#Ubuntu指令
python3 -m pip install -r  requirements.txt

#国内用户推荐使用清华源安装
#Windows指令，推荐使用powershell运行
py -3 -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
#Ubuntu指令
python3 -m pip install -r  requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

编写文档

安装好后，在项目的文档目录中添加rst或markdown文件即可， 建议使用vs code来编写文档，它非常方便预览文档， 可参考《 使用vscode编写rst文件》来搭建vscode预览sphinx文档的环境。

编写文档时的语法和规范可参考以下内容：

• 《 ReST基础语法》
• 《 野火sphinx文档规范》
• 《 Markdown示例》

编译文档

如果使用了vscode的rst插件，可以直接保存rst文件后它会自动编译并可预览。

也可以手动编译，到文档源码所在的makefile目录，执行如下命令：

#在文档的makefile目录下执行

#Windows指令
make.bat  html
#Ubuntu指令
make html

在设定的build或_build的html目录下会生成静态的html文件。可直接使用这些静态的html文件制作网站。

在本地预览文档

vscode插件预览有时不够完整，可以在本地开启一个python服务器来预览。 进入到生成的_build/html目录，运行如下指令：

#在生成的html目录执行如下指令
#Windows
py -3 -m http.server  8000

#Ubuntu
python3 -m http.server 8000

运行指令后，在浏览器中打开 http://localhost:8000 即可查看生成的静态网页。

允许其它主机预览文档

类似地，若要允许其它主机访问自己的文档，执行如下命令即可

#在生成的html目录执行如下指令
#Windows
py -3 -m http.server --bind 0.0.0.0 8000

#Ubuntu
python3 -m http.server --bind 0.0.0.0 8000

运行指令后，在浏览器中打开 http://主机IP:8000 即可查看生成的静态网页。

清除编译输出

有时html文件不会完全达到我们修改rst后的效果，这可能是因为之前的旧文件影响， 这时可以先清除编译输出再重新编译。

#清除编译输出

#Windows指令
make.bat  clean
#Ubuntu指令
make clean

#重新编译

#Windows指令
make.bat  html
#Ubuntu指令
make html

创建全新的sphinx文档

若不想使用本工程模版，可以使用如下指令创建全新的文档。

sphinx-quickstart

按照提示回答问题即可。 推荐使用默认的_build目录，与vscode保持一致。 其中提示语言时可以使用这个中文代码：zh_CN

sphinx默认不支持markdown语法，要支持的话请参考本模版的conf.py文件配置。

使用vscode编写rst文件

使用vscode编写sphinx文档非常方便，可以即时预览和自动编译。

rst vscode插件说明页：https://docs.restructuredtext.net/index.html

另外，vscode默认支持markdown单个文件的预览。

reStructuredText插件

需要安装的vscode插件：

• python
• reStructuredText

安装python插件后，要选择使用python3的解释器，不要使用python2。

安装reStructuredText插件后，打开rst文件，点击预览按钮。

会提示使用sphinx还是doctuil工具，我们选择使用sphinx。

若配置正确，稍等一会即可在右侧看到预览效果。

Table Formater插件

使用Table Formater可以方便格式化表格，支持markdown和rst https://marketplace.visualstudio.com/items?itemName=shuworks.vscode-table-formatter

插件名：Table Formatter

安装后通过Ctrl-Shift-P调用 Table: Format Current 或 Table: Format All

docx批量转rst方法

按章分割word文档

1.将所需转换的文档放入一个新的文件夹中

2.打开文档，进入大纲视图

3.合理选择显示级别，取消显示文本格式的选项后将显示本文档所有的章节名

4.点击第n章前的加号按钮，选中本章，点击显示文档按钮，出现创建选项

5.点击创建按钮之后如图所示

6.所有章都按上述方法操作，点击保存

7.文件夹中就出现了分割好的单独docx格式的文件，删除原来整本的文档

批量将分割后的docx转换为rst

1.将分割后的文件改成对应的英文名以方便转换

2.新建一个文本文档，内容如下，获取当前列表中的文件名

DIR *.* /B >LIST.TXT

3.将新建文本文档的后缀名改为 .bat后双击运行得到 了LIST.TXT ，

4.用notepad++打开LIST.TXT,删除图中的两行

5.鼠标：alt+鼠标左键选择中所有的行。键盘：alt+shift+方向鍵将位置调整到行首。输入rstfromdocx -lurg 后保存。

rstfromdocx -lurg

6.在文档所在的文件夹按住shift键和点击鼠标右键，选中打开powershell，

7.全选上面编辑好的文档列表然后复制到powershell中，鼠标右键复制，文档开始转换

8.完成后就得到了转换好的文件，将转换好的文件复制到一个新文件夹中，防止接下来的操作失败，注意备份

批量将.rest修改为.rst并删除不需要的文件

1.在新文件夹中新建一个.bat文件，并复制以下内容保存后运行

del *.py /s
del index.rest /s
del Makefile /s

for /f "tokens=* delims=" %%i in ('dir /b /a-d /s "*.rest"') do (move "%%i" "%%~dpi./../")
for /f "tokens=* delims=" %%i in ('dir /b /a-d /s "*.png"') do (move "%%i" "%%~dpi./../")
for /f "tokens=* delims=" %%i in ('dir /b /a-d /s "*.jpeg"') do (move "%%i" "%%~dpi./../")
for /f "tokens=* delims=" %%i in ('dir /b /a-d /s "*.jpg"') do (move "%%i" "%%~dpi./../")
for /f "tokens=* delims=" %%i in ('dir /b /a-d /s "*.bmp"') do (move "%%i" "%%~dpi./../")

echo.
echo 正在删除当前目录及子目录中所有的空文件夹，请稍后......
echo -------------------------------------------------------------
cd. > listnull.txt
for /f "delims=" %%i in ('dir /ad /b /s') do (
dir /b "%%i" | findstr .>nul || echo %%i >> listnull.txt
)

set /a sum=0
for /f "tokens=*" %%i in (listnull.txt) do (
rd /q "%%i"
echo 成功删除空目录：%%i
set /a sum=sum+1
)

echo -------------------------------------------------------------
echo 共成功删除%cd%目录及其子目录下%sum%个空文件夹！
echo.
set sum=

ren *.rest *.rst

del listnull.txt

exit

上述代码的作用是删除不需要的文件和空文件夹，并将图片文件移动到上一级目录下，然后将rest更名为rst

2.新建一个media文件夹，并将存放图片的文件夹移动至media文件夹，至此，批量转换完成

ReST基础语法

rst的基础语法和markdown差不多，

可以使用这个在线的rst编辑器了解相关语法：rst在线编辑器

• sphinx语法官网：http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
• restruct语法官网：http://docutils.sourceforge.net/rst.html

下面是常用语法：

语法：

一级标题
==============================

二级标题
~~~~~~~~~~~~~~~

三级标题
------------------

四级标题
^^^^^^^^^^^^^^^^^^^^^

五级标题
"""""""""""""""""

六级标题
*****************

**强调**

*斜体*

``monospace,会变色，具体作用不清楚``

无序列表
---------------------------
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh

有序列表
------------------------
支持数字、大小写字母和罗马数字

1. hhhhhhhh
#. hhhhhhhh
#. hhhhhhhh
#. hhhhhhhh
#. hhhhhhhh
#. hhhhhhhh

a. hhhhhhhh
#. hhhhhhhh
#. hhhhhhhh
#. hhhhhhhh
#. hhhhhhhh
#. hhhhhhhh

效果：

强调

斜体

monospace,会变色，具体作用不清楚

无序列表

• hhhhhhhh
• hhhhhhhh
• hhhhhhhh
• hhhhhhhh
• hhhhhhhh
• hhhhhhhh

有序列表

支持数字、大小写字母和罗马数字

1. hhhhhhhh
2. hhhhhhhh
3. hhhhhhhh
4. hhhhhhhh
5. hhhhhhhh
6. hhhhhhhh

1. hhhhhhhh
2. hhhhhhhh
3. hhhhhhhh
4. hhhhhhhh
5. hhhhhhhh
6. hhhhhhhh

表格

表格语法说明：http://docutils.sourceforge.net/docs/ref/rst/directives.html#csv-table

推荐使用列表式表格，修改比较方便

列表式表格

语法：

.. list-table:: Frozen Delights!
    :widths: 15 10 30
    :header-rows: 1

    * - Treat
      - Quantity
      - Description
    * - Albatross
      - 2.99
      - On a stick!
    * - Crunchy Frog
      - 1.49
      - If we took the bones out, it wouldn't be
        crunchy, now would it?
    * - Gannet Ripple
      - 1.99
      - On a stick!

效果：

Frozen Delights!

Treat	Quantity	Description
Albatross	2.99	On a stick!
Crunchy Frog	1.49	If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple	1.99	On a stick!

普通表格

表格使用 == 号制作

语法示例：

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

效果：

A	B	A and B
False	False	False
True	False	False
False	True	False
True	True	True

在vscode可安装插件方便格式化表格：https://marketplace.visualstudio.com/items?itemName=shuworks.vscode-table-formatter

安装后通过Ctrl-Shift-P调用 Table: Format Current 或 Table: Format All

CSV表格

使用CSV编写

.. csv-table:: Frozen Delights!
    :header: "Treat", "Quantity", "Description"
    :widths: 15, 10, 30

    "Albatross", 2.99, "On a stick!"
    "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
    crunchy, now would it?"
    "Gannet Ripple", 1.99, "On a stick!"

效果：

Frozen Delights!

Treat	Quantity	Description
Albatross	2.99	On a stick!
Crunchy Frog	1.49	If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple	1.99	On a stick!

超链接与文件引用

参考说明：http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role

超链接

语法：

直接嵌入网址：
`野火公司官网 <http://www.embedfire.com>`_

使用引用的方式把具体网址定义在其它地方： `野火公司官网`_

.. _野火公司官网: http://www.embedfire.com

效果：

直接嵌入网址：

野火公司官网

使用引用的方式把具体网址定义在其它地方： 野火公司官网

引用

引用图片、表格

在图片、表格上面加一个引用标签，然后通过 ref指令引用。 语法：

.. _my-reference-label支持中文:

.. figure: ../media/rest-syntax/pic-video/logo.png
   :alt: 野火logo
   :align: center

引用方式 :ref:`my-reference-label支持中文` 。

效果：

必须写这个图片名

引用方式 必须写这个图片名 。

表格引用：

.. _拨码开关启动配置表:

.. table:: 拨码开关启动配置表

==== ====== ========== ==== == ===
编号 名称   NAND FLASH eMMC SD USB
==== ====== ========== ==== == ===
1    MODE0  0          0    0  1
2    MODE1  1          1    1  0
3    CFG1-4 1          0    0  X
4    CFG1-5 0          1    0  X
5    CFG1-6 0          1    1  X
6    CFG1-7 1          0    0  X
7    CFG2-3 0          1    0  X
8    CFG2-5 0          0    1  X
==== ====== ========== ==== == ===

引用示例 :ref:`拨码开关启动配置表` 。
自定义名称引用 :ref:`自定义名称 <拨码开关启动配置表>` 。

效果：

拨码开关启动配置表

编号	名称	NAND FLASH	eMMC	SD	USB
1	MODE0	0	0	0	1
2	MODE1	1	1	1	0
3	CFG1-4	1	0	0	X
4	CFG1-5	0	1	0	X
5	CFG1-6	0	1	1	X
6	CFG1-7	1	0	0	X
7	CFG2-3	0	1	0	X
8	CFG2-5	0	0	1	X

引用示例 拨码开关启动配置表 。 自定义名称引用 自定义名称 。

引用文档

语法：

自定义引用文字

:doc:`引用本地的其它rst文档,rst后缀要省略，如about_us <../about_us>`

使用标题文字
:doc:`../about_us`

效果：

自定义引用文字

引用本地的其它rst文档,rst后缀要省略，如about_us

使用标题文字 关于野火

使用标签引用文档

要在被引用的文件头定义标签，如about_us.rst文件头写 “about_embedfire” 的标签，具体请查看该文档的源码

语法：

:ref:`自定义链接文字 <about_embedfire>`

:ref:`about_embedfire`

效果：

about_embedfire

关于野火

若要跨文档引用标题，可以使用自动切片扩展插件，它的使用方式如下：

某个文档：

=============
Some Document
=============


Internal Headline
=================

然后在另一个文档引用：

===============
Some Other Doc
===============


A link-  :ref:`Internal Headline`

此扩展程序是内置的，因此您只需编辑即可 conf.py

extensions = [
    .
    . other
    . extensions
    . already
    . listed
    .
    'sphinx.ext.autosectionlabel',
]

您唯一需要注意的是，现在您无法在整个文档集合中复制内部标题。

引用非rst文档

会呈现出点击后下载文件的效果。注意这种引用方式在生成pdf文件时链接会无效。

语法：

:download:`引用非rst的本地文档 <../requirements.txt>`.

效果：

引用非rst的本地文档.

代码高亮

参考说明： http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#toctree-directive

支持的高亮语言： https://pygments.org/docs/lexers#lexers-for-various-shells

快速定义代码块

使用简便的预定义高亮语法高亮缩进，默认不带语言说明的都使用highlight定义的语言高亮， 然后可以直接使用“::”两个冒号代替“code-block”指令快速定义其它代码块， 直到下一个highlight指令，才会改变语言：

.. highlight:: sh

此指令后如下的“::”定义的块都会以sh语法进行高亮，直到遇到下一条highlight指令。

::

   #此命令在主机执行
   sudo apt install python
   echo "helloworld,this is a script test!"

效果：

#此命令在主机执行
sudo apt install python
echo "helloworld,this is a script test!"

code-block代码高亮

shell 高亮测试

高亮语法：

.. code-block:: sh
   :caption: test
   :name: test333
   :emphasize-lines: 2
   :linenos:

   #此命令在主机执行
   sudo apt install python
   echo "helloworld,this is a script test!"

效果：

sh test

#此命令在主机执行
sudo apt install python
echo "helloworld,this is a script test!"

C高亮测试

语法：

.. code-block:: c
   :caption: c test
   :emphasize-lines: 4,5
   :linenos:

   #include <stdio.h>

   int main()
   {
      printf("hello, world! This is a C program.\n");
      for(int i=0;i<10;i++ ){
         printf("output i=%d\n",i);
      }

      return 0;
   }

效果：

c test

#include <stdio.h>

int main()
{
   printf("hello, world! This is a C program.\n");
   for(int i=0;i<10;i++ ){
      printf("output i=%d\n",i);
   }

   return 0;
}

verilog高亮测试

语法：

使用verilog或v进行高亮

.. code-block:: v
   :caption: verilog test
   :emphasize-lines: 4,5
   :linenos:

   module  key_filter
   #(
      parameter CNT_MAX = 20'd999_999 //计数器计数最大值
   )
   (
      input   wire    sys_clk     ,   //系统时钟50Mhz
      input   wire    sys_rst_n   ,   //全局复位
      input   wire    key_in      ,   //按键输入信号

      output  reg     key_flag        //key_flag为1时表示消抖后检测到按键被按下
                                       //key_flag为0时表示没有检测到按键被按下
   );

效果：

verilog test

module  key_filter
#(
   parameter CNT_MAX = 20'd999_999 //计数器计数最大值
)
(
   input   wire    sys_clk     ,   //系统时钟50Mhz
   input   wire    sys_rst_n   ,   //全局复位
   input   wire    key_in      ,   //按键输入信号

   output  reg     key_flag        //key_flag为1时表示消抖后检测到按键被按下
                                    //key_flag为0时表示没有检测到按键被按下
);

literalinclude直接嵌入本地文件并高亮

嵌入整个文件

直接嵌入文件，包含标题、代码语言、高亮、带编号以及名称方便引用。

插入C代码

.. literalinclude:: ../../base_code/hello.c
   :caption: ../../base_code/hello.c
   :language: c
   :emphasize-lines: 5,7-12
   :linenos:
   :name: hello.c

效果：

../../base_code/hello.c

/* $begin hello */
#include <stdio.h>

int main() 
{
	printf("hello, world! This is a C program.\n");
	for(int i=0;i<10;i++ ){
		printf("output i=%d\n",i);
	}

	return 0;
}
/* $end hello */

插入shell代码

语法：

.. literalinclude:: ../../base_code/hello_world.sh
   :caption: ../../base_code/hello_world.sh
   :language: sh
   :linenos:

效果：

../../base_code/hello_world.sh

echo "helloworld,this is a script test!"

插入Makefile代码

语法：

.. literalinclude:: ../../base_code/Makefile
   :caption: ../../base_code/Makefile
   :language: makefile
   :linenos:

效果：

../../base_code/Makefile

#生成的可执行文件名

hello:hello.o
	gcc -o hello hello.o

#生成规则
hello.o:hello.c
	gcc -c hello.c -o hello.o

#伪目标
.PHONY:clean
clean:
	rm -f *.o hello

嵌入文件的某部分

通过lines指定嵌入文件的某些行。

语法：

.. literalinclude:: ../../base_code/hello.c
   :caption: ../../base_code/hello.c
   :language: c
   :linenos:
   :lines: 1,3,5-8

效果：

../../base_code/hello.c

/* $begin hello */

{
	printf("hello, world! This is a C program.\n");
	for(int i=0;i<10;i++ ){
		printf("output i=%d\n",i);

文件对比

语法：

.. literalinclude:: ../../base_code/hello.c
:diff: ../../base_code/hello_diff.c

效果：

--- /home/docs/checkouts/readthedocs.org/user_builds/ebf-contribute-guide/checkouts/latest/base_code/hello_diff.c
+++ /home/docs/checkouts/readthedocs.org/user_builds/ebf-contribute-guide/checkouts/latest/base_code/hello.c
@@ -5,7 +5,7 @@
 {
 	printf("hello, world! This is a C program.\n");
 	for(int i=0;i<10;i++ ){
-		printf("diff output i=%d\n",i);
+		printf("output i=%d\n",i);
 	}
 
 	return 0;

图片与视频

添加图片的sphinx说明：http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html 添加图片的rst官方说明：

图片

图片原文件统一存储在引用文档所在的同级目录的 media 文件夹下。

显示图片直接使用image或figure指令，无特殊情况的话我们书籍图片要求使用居中方式显示， 还需要添加“alt”选项指定图片的描述（类似doc中的题注），以便图片加载失败时显示文字

不要使用bmp图片 ，bmp图片在生成pdf的时候会丢失，所以不要使用bmp格式的图片。

figure命令

语法：

.. figure: ../media/rest-syntax/pic-video/logo.png
   :alt: 野火logo
   :align: center
   :caption: 野火logo

效果：

image命令：

语法：

.. image:: ../media/rest-syntax/pic-video/logo.png
   :align: center
   :alt: 野火logo

效果：

以下的图片显示方式是word自动转换的结果，使用这种方式无法以居中形式显示图片，所以我们要修改。

它的原理是使用“||”类似宏的方式替换指令，使rst源码看起来更简洁，但不能居中显示。

语法：

|logo|,使用"|宏名|"的形式替换文字。

.. |logo| image:: ../media/rest-syntax/pic-video/logo.png

效果：

,使用”|”宏名”|”的形式替换文字。

图片还可以使用 width、heigh、scale等参数，但不推荐使用，设置过width、height参数的图片， 在页面可以点击查看原图。

语法：

.. image:: ../media/rest-syntax/pic-video/logo.png
   :align: center
   :width: 5.63529in
   :height: 0.97222in

效果：

视频

使用raw指令插入html代码。 直接粘贴视频网站的通用html代码，不过貌似不能放大。

在vscode可能无法预览，直接在浏览器中看即可。

注解

TODO：目前还不知道如何放大，以及点击后到具体的视频网站播放。

语法：

.. raw:: html

<iframe src="//player.bilibili.com/player.html?aid=70961112&cid=122951107&page=1" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>

效果：

语法：

.. raw:: html

<iframe height=498 width=510 src='http://player.youku.com/embed/XMzk2MzQxNTQ3Ng==' frameborder=0 'allowfullscreen'></iframe>

数学符号和公式

数学符号和公式

上标

使用sub表示平方等符号：

语法

I\ :sup:`2`\ C

效果：

I²C

特殊提示

特殊提示支持警告、重要、提示、注意等标签，适合做显眼的用途。

• attention
• caution
• danger
• error
• hint
• important
• note
• tip
• warning

语法：

.. note:: This is a note admonition.
 This is the second line of the first paragraph.

 - The note contains all indented body elements
   following.
 - It includes this bullet list.

.. hint:: This is a hint admonition.

.. important:: This is a important admonition.

.. tip:: This is a tip admonition.

.. warning:: This is a warning admonition.

.. caution:: This is a caution admonition.

.. attention:: This is a attention admonition.

.. error:: This is a error admonition.

.. danger:: This is a danger admonition.

效果：

注解

This is a note admonition. This is the second line of the first paragraph.

• The note contains all indented body elements following.
• It includes this bullet list.

提示

This is a hint admonition.

重要

This is a important admonition.

小技巧

This is a tip admonition.

警告

This is a warning admonition.

警告

This is a caution admonition.

注意

This is a attention admonition.

错误

This is a error admonition.

危险

This is a danger admonition.

rst的指令和角色（directive and role）

• directive说明：http://docutils.sourceforge.net/docs/ref/rst/directives.html
• role说明：http://docutils.sourceforge.net/docs/ref/rst/roles.html

rst使用directive和role进行特殊操作。

directive

directive的格式为：

.. directive名:: 参数
   :参数:
   :参数:

role

role的格式为：

:role名: 内容

野火sphinx文档规范

开源项目的整体目录：

├── README                    说明文档或软链接至documentation中的说明，方便github阅读
├── base_code                 配套代码
└── documentation             配套文档
    ├── faq                   存储常见问题的文档
    ├── about_us.rst          关于我们
    ├── _build                文档编译输出目录
    ├── conf.py               sphinx配置文件
    ├── contribute            如何参与项目，贡献与投稿的说明
    ├── foreword.rst          前言
    ├── index.rst             目录
    ├── make.bat
    ├── Makefile
    ├── media                 文档中使用的图片文件
    ├── requirements.txt      文档的python依赖
    ├── _static
    ├── _templates
    ├── TODO.rst              待完成的内容，发布的任务列表

注意：每次新添加了rst文档，必须要修改documentation文件夹下的index.rst文件，将新增的rst文件，添加到对应的地方。

图片

文档引用的图片存储在文档源码目录下的media文件夹中，按部分、章节及文档分目录存储。

图片要直接使用如下形式,方便居中：

.. image:: media/logo.png
   :align: center

不要使用如下形式，如下形式是docx转换后的格式，它不支持居中，见到要把它改好。

|logo|

.. |logo| image:: media/logo.png

rst格式检查

使用vscode的rst插件在编写时就会有格式检查。编写文档时应尽量满足该格式检查的规范。 对于docx转rst后的不规范文档，做到见一个改一个。

make html时，编译会有提示输出，尽量让它不输出的warning。

文档编码和回车

文档编码统一用“utf-8”， 回车使用“LF”，不要使用“CRLF”，文档编码和回车可在VS-Code的右下角设置。

代码引用

超过3行的代码要加上行号、并用caption名指明代码片段的名，对于引用的代码文件，使用caption指明引用的路径名。

如以下语法：

.. literalinclude:: ../../base_code/hello.c
   :caption: ../../base_code/hello.c
   :language: c
   :linenos:

类似docx的题注引用

rst可通过链接实现类似doc的题注引用，它通过给内容添加 :name: 属性来实现， 代码、图片、表格等都可以使用这种方式，使用 :name: 属性来定义引用名，通过引用名+下划线来实现引用：

语法：

.. literalinclude:: ../../base_code/hello.c
   :caption: ../../base_code/hello.c
   :language: c
   :name: 代码清单或自己起的引用名字
   :linenos:

引用的方式是使用 ":name:"定义的名字加下划线 "_",如：

代码清单或自己起的引用名字_

效果：

../../base_code/hello.c

/* $begin hello */
#include <stdio.h>

int main() 
{
	printf("hello, world! This is a C program.\n");
	for(int i=0;i<10;i++ ){
		printf("output i=%d\n",i);
	}

	return 0;
}
/* $end hello */

引用的方式是使用 “:name:”定义的名字加下划线 “_”,如：

代码清单或自己起的引用名字

语法：

.. image:: ../media/rest-syntax/pic-video/logo.png
   :align: center
   :name: 野火logo

引用的方式是使用 ":name:"定义的名字加下划线 "_",如：

野火logo_

效果：

引用的方式是使用 “:name:”定义的名字加下划线 “_”,如：

野火logo

语法：

.. list-table:: Frozen Delights!
    :widths: 15 10 30
    :header-rows: 1
    :name: 测试表格

    * - Treat
      - Quantity
      - Description
    * - Albatross
      - 2.99
      - On a stick!
    * - Crunchy Frog
      - 1.49
      - If we took the bones out, it wouldn't be
        crunchy, now would it?
    * - Gannet Ripple
      - 1.99
      - On a stick!

引用的方式是使用 ":name:"定义的名字加下划线 "_",如：

测试表格_

效果：

Frozen Delights!

Treat	Quantity	Description
Albatross	2.99	On a stick!
Crunchy Frog	1.49	If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple	1.99	On a stick!

引用的方式是使用 “:name:”定义的名字加下划线 “_”,如：

测试表格_

使sphinx支持markdown

sphinx默认是不支持markdown语法的，但可以通过插件来支持。

markdown基础支持

recommonmark的PyPi说明：https://pypi.org/project/sphinx-markdown-tables/

recommonmark的sphinx说明：http://www.sphinx-doc.org/en/master/usage/markdown.html

recommonmark的使用说明：https://recommonmark.readthedocs.io/en/latest/index.html

pip install recommonmark

在conf.py添加扩支持：

extensions = ['recommonmark']

配置后就可以在sphinx中使用markdown文件了

markdown表格支持

要支持markdown的表格语法，还需要安装sphinx-markdown-tables

markdown表格支持：https://pypi.org/project/sphinx-markdown-tables/

安装：

pip install sphinx-markdown-tables

使用：

在conf.py添加扩展支持：

extensions = [
   'sphinx_markdown_tables',
]

Markdown示例

本文件的源码是一个markdown文件,也就是说在本工程中直接添加markdown即可嵌入到sphinx文档中。

关于使sphinx支持markdown的详细配置说明，请参考文档markdown-sphinx。

markdown的公式语法在sphinx可能不支持。

以下是markdown的语法使用示例

文档来源：https://www.mdeditor.com/

欢迎使用 Markdown在线编辑器 MdEditor

Markdown是一种轻量级的「标记语言」

markdown

Markdown是一种可以使用普通文本编辑器编写的标记语言，通过简单的标记语法，它可以使普通文本内容具有一定的格式。它允许人们使用易读易写的纯文本格式编写文档，然后转换成格式丰富的HTML页面，Markdown文件的后缀名便是“.md”

MdEditor是一个在线编辑Markdown文档的编辑器

MdEditor扩展了Markdown的功能（如表格、脚注、内嵌HTML等等），以使让Markdown转换成更多的格式，和更丰富的展示效果，这些功能原初的Markdown尚不具备。

Markdown增强版中比较有名的有Markdown Extra、MultiMarkdown、 Maruku等。这些衍生版本要么基于工具，如~~Pandoc~~，Pandao；要么基于网站，如GitHub和Wikipedia，在语法上基本兼容，但在一些语法和渲染效果上有改动。

MdEditor源于Pandao的JavaScript开源项目，开源地址Editor.md，并在MIT开源协议的许可范围内进行了优化，以适应广大用户群体的需求。向优秀的markdown开源编辑器原作者Pandao致敬。

Pandao editor.md

MdEditor的功能列表演示

标题H2

标题H3

标题H4

标题H5

标题H5

字符效果和横线等

---

~~删除线~~ 删除线（开启识别HTML标签时）

斜体字 斜体字

粗体 粗体

粗斜体 粗斜体

上标：X₂，下标：O²

缩写(同HTML的abbr标签)

即更长的单词或短语的缩写形式，前提是开启识别HTML标签时，已默认开启

The HTML specification is maintained by the W3C.

引用 Blockquotes

引用文本 Blockquotes

引用的行内混合 Blockquotes

引用：如果想要插入空白换行即<br />标签，在插入处先键入两个以上的空格然后回车即可，普通链接。

锚点与链接 Links

普通链接 普通链接带标题 直接链接：https://www.mdeditor.com [锚点链接][anchor-id] [anchor-id]: https://www.mdeditor.com/ mailto:test.test@gmail.com GFM a-tail link @pandao 邮箱地址自动链接 test.test@gmail.com www@vip.qq.com

@pandao

多语言代码高亮 Codes

行内代码 Inline code

执行命令：npm install marked

缩进风格

即缩进四个空格，也做为实现类似 <pre> 预格式化文本 ( Preformatted Text ) 的功能。

<?php
    echo "Hello world!";
?>

预格式化文本：

| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |

JS代码

function test() {
	console.log("Hello world!");
}

HTML 代码 HTML codes

<!DOCTYPE html>
<html>
    <head>
        <mate charest="utf-8" />
        <meta name="keywords" content="Editor.md, Markdown, Editor" />
        <title>Hello world!</title>
        <style type="text/css">
            body{font-size:14px;color:#444;font-family: "Microsoft Yahei", Tahoma, "Hiragino Sans GB", Arial;background:#fff;}
            ul{list-style: none;}
            img{border:none;vertical-align: middle;}
        </style>
    </head>
    <body>
        <h1 class="text-xxl">Hello world!</h1>
        <p class="text-green">Plain text</p>
    </body>
</html>

图片 Images

图片加链接 (Image + Link)：

Follow your heart.

---

列表 Lists

无序列表（减号）Unordered Lists (-)

• 列表一
• 列表二
• 列表三

无序列表（星号）Unordered Lists (*)

• 列表一
• 列表二
• 列表三

无序列表（加号和嵌套）Unordered Lists (+)

• 列表一
• 列表二
  • 列表二-1
  • 列表二-2
  • 列表二-3
• 列表三
  • 列表一
  • 列表二
  • 列表三

有序列表 Ordered Lists (-)

1. 第一行
2. 第二行
3. 第三行

GFM task list

• [x] GFM task list 1
• [x] GFM task list 2
• [ ] GFM task list 3
  • [ ] GFM task list 3-1
  • [ ] GFM task list 3-2
  • [ ] GFM task list 3-3
• [ ] GFM task list 4
  • [ ] GFM task list 4-1
  • [ ] GFM task list 4-2

---

绘制表格 Tables

项目	价格	数量
计算机	$1600	5
手机	$12	12
管线	$1	234

First Header	Second Header
Content Cell	Content Cell
Content Cell	Content Cell

First Header	Second Header
Content Cell	Content Cell
Content Cell	Content Cell

Function name	Description
help()	Display the help window.
destroy()	Destroy your computer!

Left-Aligned	Center Aligned	Right Aligned
col 3 is	some wordy text	$1600
col 2 is	centered	$12
zebra stripes	are neat	$1

Item	Value
Computer	$1600
Phone	$12
Pipe	$1

---

特殊符号 HTML Entities Codes

© & ¨ ™ ¡ £ & < > ¥ € ® ± ¶ § ¦ ¯ « ·

X² Y³ ¾ ¼ × ÷ »

18ºC “ ‘

[========]

Emoji表情 :smiley:

Blockquotes :star:

GFM task lists & Emoji & fontAwesome icon emoji & editormd logo emoji :editormd-logo-5x:

• [x] :smiley: @mentions, :smiley: #refs, links, formatting, and tags supported :editormd-logo:;
• [x] list syntax required (any unordered or ordered list supported) :editormd-logo-3x:;
• [x] [ ] :smiley: this is a complete item :smiley:;
• [ ] []this is an incomplete item test link :fa-star: @pandao;
• [ ] [ ]this is an incomplete item :fa-star: :fa-gear:;
  • [ ] :smiley: this is an incomplete item test link :fa-star: :fa-gear:;
  • [ ] :smiley: this is :fa-star: :fa-gear: an incomplete item test link;

反斜杠 Escape

*literal asterisks*

[========]

科学公式 TeX(KaTeX)

$$E=mc^2$$

行内的公式$$E=mc^2$$行内的公式，行内的$$E=mc^2$$公式。

$$x > y$$

$$(\sqrt{3x-1}+(1+x)^2)$$

$$\sin(\alpha)^{\theta}=\sum_{i=0}^{n}(x^i + \cos(f))$$

多行公式：

\displaystyle
\left( \sum\_{k=1}^n a\_k b\_k \right)^2
\leq
\left( \sum\_{k=1}^n a\_k^2 \right)
\left( \sum\_{k=1}^n b\_k^2 \right)

\displaystyle
    \frac{1}{
        \Bigl(\sqrt{\phi \sqrt{5}}-\phi\Bigr) e^{
        \frac25 \pi}} = 1+\frac{e^{-2\pi}} {1+\frac{e^{-4\pi}} {
        1+\frac{e^{-6\pi}}
        {1+\frac{e^{-8\pi}}
         {1+\cdots} }
        }
    }

f(x) = \int_{-\infty}^\infty
    \hat f(\xi)\,e^{2 \pi i \xi x}
    \,d\xi

分页符 Page break

Print Test: Ctrl + P

[========]

绘制流程图 Flowchart

st=>start: 用户登陆
op=>operation: 登陆操作
cond=>condition: 登陆成功 Yes or No?
e=>end: 进入后台

st->op->cond
cond(yes)->e
cond(no)->op

[========]

绘制序列图 Sequence Diagram

Andrew->China: Says Hello
Note right of China: China thinks\nabout it
China-->Andrew: How are you?
Andrew->>China: I am good thanks!

End

使用pandoc进行文档转换

使用pandoc可以方便地对文档的格式进行相互转换。

安装

pandoc安装说明：https://github.com/jgm/pandoc/blob/master/INSTALL.md

pandoc用户手册：https://pandoc.org/MANUAL.html

根据系统按它的说明下载对应的安装包即可，ubuntu下不要直接用apt安装，apt安装的版本太旧。

在ubuntu下可以使用如下命令查看pandoc的说明：

man pandoc

docx转rst

使用python安装rstdoc扩展包，方便转换：https://pypi.org/project/rstdoc/

docx转rst操作步骤：

• 先把docx文档按章节分开，一个章节一个docx文档，不然整个文档转换可能太大， 导致错误，而且整个文档转换图片或内容不方便处理。
• 使用rstfromdocx命令一个个文档转换成rst

使用如下指令转换

#doc1为要转换的文档
rstfromdocx -lurg doc1.docx

命令执行后会生成与文档名相同的目录，目录下是sphinx形式的rest文档， 把rest文档复制至新的书籍目录并把后缀改为rst，media下的图片也放到目标书籍的同级目录即可。

小技巧

在Windows转换后，生成的文件目录引用使用的路径是“”，而sphinx路径只支持“/”， 所以图片之类的引用路径要注意修改。

pandoc rst转docx

rstdocx插件据说可以更完美地把rst转成docx，但还不清楚rstdocx插件如何把rst转成docx，但用pandoc可满足基本要求。

pandoc rstfile.rst  -f   rst  -t docx  -o targetdocfile.docx  --data-dir=sourcedir  --reference-doc=module.docx

• 其中rstfile.rst是源文件，-f 指源格式，-f 指目标格式
• -o指定的是输出文件
• –data-dir=指定的是依赖目录
• –reference-doc=是docx模版文件，使用模版文件转换可以把标题之类的格式搞得更规范

reference-doc模版及说明：https://pandoc.org/MANUAL.html#option–reference-doc

pandoc docx转rst

与rst转docx类似，输出的图片目录可以使用这个参数设置：

–extract-media=DIR

常见问题

版权说明

野火电子保留本项目的所有版权。

公司组织有生存的压力，因为开源而导致生存不下去，是有GEEK精神的人不愿看到的事情。 由于我们还不熟悉各种版权条例，所以关于版权的问题还在选择中。

目前我们保留本项目的所有版权，但我们秉承开源的心是不变的。 如果你使用本项目不是用于商业目的，基本不需要考虑版权问题。

我们主要担忧的商业目的如下，列出来的意思是如果用于以下目的，我们极有可能会追究版权。

• 同业竞争，目前开发板是我们主要的盈利来源，禁止把本项目用于其它开发板项目。
• 文档出版，项目中包含的文档我们随时会提交至出版社出版，所以我们保留文档出版的权利。 如果你只是在自己的文章中使用了本项目文档中的内容，需要注明来源。