2.12. Rest文档规范¶
2.12.1. 使用图片¶
文档引用的图片存储在文档源码目录下的media文件夹中，按部分、章节及文档分目录存储。
图片要直接使用如下形式,方便居中：
.. image:: ./logo.png
:align: center
不要使用如下形式，如下形式是docx转换后的格式，它不支持居中，见到要把它改好。
|logo|
.. |logo| image:: media/logo.png
2.12.2. rst格式检查¶
使用vscode的rst插件在编写时就会有格式检查。编写文档时应尽量满足该格式检查的规范。 对于docx转rst后的不规范文档，做到见一个改一个。
make html时，编译会有提示输出，尽量让它不输出的warning。
2.12.3. 文档编码和回车¶
文档编码统一用“utf-8”， 回车使用“LF”，不要使用“CRLF”，文档编码和回车可在VS-Code的右下角设置。
2.12.4. 代码引用¶
超过3行的代码要加上行号、并用caption名指明代码片段的名，对于引用的代码文件，使用caption指明引用的路径名。
如以下语法：
.. literalinclude:: ./hello.c
:caption: ./hello.c
:language: c
:linenos:
2.12.5. 交叉引用¶
rst可实现交叉引用，它通过给内容添加 :name: 属性来实现，
代码、图片、表格等都可以使用这种方式，使用 :name: 属性来定义引用名，通过 引用名+下划线 来实现引用：
语法：
.. literalinclude:: ../../base_code/hello.c
:caption: ../../base_code/hello.c
:language: c
:name: 代码清单或自己起的引用名字
:linenos:
引用的方式是使用 ":name:"定义的名字加下划线 "_",如：
代码清单或自己起的引用名字_
效果：
1/* $begin hello */
2#include <stdio.h>
3
4int main()
5{
6 printf("hello, world! This is a C program.\n");
7 for(int i=0;i<10;i++ ){
8 printf("output i=%d\n",i);
9 }
10
11 return 0;
12}
13/* $end hello */
14
引用的方式是使用 “:name:”定义的名字加下划线 “_”,如：
语法：
.. image:: ./logo.png
:align: center
:name: 野火logo
引用的方式是使用 ":name:"定义的名字加下划线 "_",如：
野火logo_
效果：
.. image:: logo.png
:align: center
: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:"定义的名字加下划线 "_",如：
测试表格_
效果：
.. 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!
引用的方式是使用 “:name:”定义的名字加下划线 “_”,如：
测试表格_