8. 野火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文件，添加到对应的地方。

8.1. 图片

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

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

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

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

|logo|

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

8.2. rst格式检查

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

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

8.3. 文档编码和回车

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

8.4. 代码引用

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

如以下语法：

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

8.5. 类似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:”定义的名字加下划线 “_”,如：

测试表格_