7. 野火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 待完成的内容,发布的任务列表
7.1. 图片¶
文档引用的图片存储在文档源码目录下的media文件夹中,按部分、章节及文档分目录存储。
图片要直接使用如下形式,方便居中:
.. image:: media/logo.png
:align: center
不要使用如下形式,如下形式是docx转换后的格式,它不支持居中,见到要把它改好。
|logo|
.. |logo| image:: media/logo.png
7.2. rst格式检查¶
使用vscode的rst插件在编写时就会有格式检查。编写文档时应尽量满足该格式检查的规范。 对于docx转rst后的不规范文档,做到见一个改一个。
make html时,编译会有提示输出,尽量让它不输出的warning。
7.3. 代码引用¶
超过3行的代码要加上行号、并用caption名指明代码片段的名,对于引用的代码文件,使用caption指明引用的路径名。
如以下语法:
.. literalinclude:: ../../base_code/hello.c
:caption: ../../base_code/hello.c
:language: c
:linenos: