文档结构

良好的文档结构和统一规范的文件名可以更好的理解文档，方便文档的维护和多人编辑。建议使用如下结构：

project_name/
├── make.bat
├── Makefile
├── build/
└── source/
    ├── conf.py
    ├── index.rst
    ├── welcome.rst
    ├── chapter/
    └── img/

• make.bat 快速构建文档的脚本工具

• build/ 构建文档完成后的输出目录（默认）

• source/ 文档的源目录

• source/conf.py 文档的配置文件

• source/index.rst 文档的“目录树”，也叫做文档的主文件

• source/welcome.rst 文档的前言文件

• source/chapter/ 文档的章节（每个章节一个目录）

• source/img/ 图片文件的存放目录

文件命名

文件名要根据文件的内容来命名，使文档在交叉引用时更明白、方便。文件命名需要遵循：

1. 文件名只能包含小写字母、数字和下划线。

2. 多单词用下划线连接，例如：document_retrieval.rst。

3. 文件名中下划线最多使用三个，例如：the_book_of_changes.rst。

4. 英文单词不使用缩写

注意

Sphinx 保留了一些文档名称供自己使用，类似于编程语言中的关键字。这些关键字名称（genindex、modindex、search）不能用于文件名。

图片命名

图片文件名依据“引用文件名 + 下划线 + 序号”而命名。序号占用两位，不够用零补齐。 例如，在 welcome.rst 文件中插入图片时，命名为 welcome_01.jpg、welcome_02.jpg（依此类推）。

对于需要多次引用的图片，例如 Icon 图标，可以使用原意单词命名，命名规则参见 文件命名 。

提示

图片的大小

根据输出用途不同，图片的大小应相应的调整。用于显示屏幕（网页）时，建议图片宽度最大不超过 700px。用于打印时，应使用高清图片，并根据打印尺寸的大小选择相应尺寸，打印为 A4 大小时，建议图片宽度最大不超过 1350px。