开源项目的整体目录: :
├── 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
注意:每次新添加了rst文档,必须要修改documentation文件夹下的index.rst文件,将新增的rst文件,添加到对应的地方。
文档引用的图片存储在文档源码目录下的media文件夹中,按部分、章节及文档分目录存储。
图片要直接使用如下形式,方便居中:
.. image:: media/logo.png
:align: center
不要使用如下形式,如下形式是docx转换后的格式,它不支持居中,见到要把它改好。 :
|logo|
.. |logo| image:: media/logo.png
使用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:
rst可通过链接实现类似doc的题注引用,它通过给内容添加 :name:
属性来实现, 代码、图片、表格等都可以使用这种方式,使用 :name:
属性来定义引用名,通过引用名+下划线来实现引用:
语法: :
.. literalinclude:: ../../base_code/hello.c
:caption: ../../base_code/hello.c
:language: c
:name: 代码清单或自己起的引用名字
:linenos:
引用的方式是使用 ":name:"定义的名字加下划线 "_",如:
代码清单或自己起的引用名字_
效果:
../../base_code/hello.c
引用的方式是使用 ":name:"定义的名字加下划线 "_",如:
语法: :
.. image:: ../media/rest-syntax/pic-video/logo.png
:align: center
:name: 野火logo
引用的方式是使用 ":name:"定义的名字加下划线 "_",如:
野火logo_
效果:
引用的方式是使用 ":name:"定义的名字加下划线 "_",如:
语法:
.. 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:"定义的名字加下划线 "_",如: