12.3. RestructuredText 文档规范

12.3.1. rst格式检查

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

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

12.3.2. 文档编码和回车

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

12.3.3. 代码的使用与引用

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

如以下语法：

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

代码引用语法：

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

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

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

效果：

代码 12.3.1 ./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: 定义的名字加下划线 _ ，如：

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