5.2. Sphinx文档修改要求¶
Sphinx通过其自身语法要求进行项目内容关联，本身无目录结构明确要求。 为了方便团队内部修改，按以下要求来做一致性约束，避免一些问题。
5.2.1. Sphinx文档项目¶
Sphinx文件项目做到对其基本的理解， 一般不需要对目录结构修改。 但章节命名一定要规范。
文件项目目录结构¶
一般使用二级目录（章、节）。
├── Makefile
└── tech-src
├── ch01_install-sphinx-env
│ ├── chapter.rst
│ ├── sec01_base
│ │ └── section.rst
│ └── sec02_conf
│ └── section.rst
├── conf.py
└── index.rst
Note
每次新添加了rst文档，需要添加到对应的地方。不必修改，由程序自动处理。
Sphinx项目每天会定时进行自动构建检查，如果有问题会相应生成 _error.txt 文件。
Warning
如果在Sphinx项目中出现 _error.txt 文件，一定要检查，将问题修改过来。
章节名称¶
章名称、节名称皆为三部分，用下划线分割。第三部分可以没有，为自动生成。
修改时主要把 sig 部分修改好，其为英文词汇，简要说明章节内容。
名称示例：
ch01_sig1_ka01
sec03_sig2_k0002
或：
ch01_sig1
sec03_sig2
5.2.2. 常规内容修改说明¶
对于 Sphinx 文件（ .rst ） 常规内容，注意修改时断行的问题。
一般情况下一句不能太长。单句成行，在句号（ 。 ）后一般要断行，方便阅读。
如果单句太长 ，则在句中合适标点后，如逗号（ ， ），引号（ ： ），进行断行。
英文文本依照中文方式处理。
5.2.3. 单个文件中的标题使用¶
对于已经存在的 .rst 文件，一般情况下不必修改标题。
如果进行修改，或新建 .rst 格式文件，使用不超过三级标题。
标题按如下使用方式约定：
一级标题：
===================
一级标题
===================
二级标题：
二级标题
==================================
三级标题：
三级标题
---------------------------------------
5.2.4. 表格¶
Warning
表格与图片的处理， 关键要注意标题与引用。
列表方式的表格¶
代码：
效果如 :numref:`tab_1` ：
.. _tab_1:
.. list-table:: 表格1标题
:widths: 25 25 50
:header-rows: 1
* - Heading row 1, column 1
- Heading row 1, column 2
- Heading row 1, column 3
* - Row 1, column 1
-
- Row 1, column 3
* - Row 2, column 1
- Row 2, column 2
- Row 2, column 3
效果如 表 5.2.1 ：
Heading row 1, column 1 |
Heading row 1, column 2 |
Heading row 1, column 3 |
|---|---|---|
Row 1, column 1 |
Row 1, column 3 |
|
Row 2, column 1 |
Row 2, column 2 |
Row 2, column 3 |
CSV 格式的表格¶
这里说明 CSV 格式的表格使用方式。 另外 CVS 也可以引用外部文件。
代码：
效果如 :numref:`tab_2`：
.. _tab_2:
.. csv-table:: 表格2标题
:file: CSV file path and name
:widths: 30, 70
:header-rows: 1
head1, head2
row1a, row1b
row2a, row2b
效果如 表 5.2.2：
head1 |
head2 |
|---|---|
row1a |
row1b |
row2a |
row2b |
5.2.5. 图片¶
添加图片的sphinx说明：http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html 添加图片的rst官方说明：
图片原文件统一存储在引用文档所在的同级目录文件夹下。
显示图片直接使用 image 或 figure 指令，无特殊情况的话我们书籍图片要求使用居中方式显示，
还需要添加 alt 选项指定图片的描述，用于网站中使用，以便图片加载失败时显示文字。
不要使用bmp图片 ，bmp图片在生成pdf的时候会丢失，所以不要使用bmp格式的图片。
Note
推荐使用 figure 命令插入图片。
figure 命令¶
figure 添加图片时可以使用标题与legend。一般在使用时要加入引用。
语法如下：
如 :numref:`fig_qgis_figure220` 。
.. _fig_qgis_figure220:
.. figure: ./logo.png
:alt: logo
:align: center
图片的标题
效果：
如图 :numref:`fig_qgis_figure220` 。
.. _fig_qgis_figure220:
.. figure:: logo.png
:alt: logo
:align: center
图片的标题
image 命令：¶
语法：
.. image:: ../../_images/logo.png
:align: center
:alt: 野火logo
以下的图片显示方式是word自动转换的结果，使用这种方式无法以居中形式显示图片，所以我们要修改。
它的原理是使用“||”类似宏的方式替换指令，使rst源码看起来更简洁，但不能居中显示。
语法：
|logo|,使用"|宏名|"的形式替换文字。
.. |logo| image:: ./logo.png
图片还可以使用 width、heigh、scale等参数，但不推荐使用，设置过width、height参数的图片， 在页面可以点击查看原图。
语法：
.. image:: ./logo.png
:align: center
:width: 5.63529in
:height: 0.97222in
5.2.6. 脚注¶
有关脚注 (ref )，使用 [#name]_ 要标记脚注位置，并在文档底部的“脚注”标题后面添加脚注正文，如下所示：
Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
生成脚注：
.. rubric:: Footnotes
.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.
还可以对脚注进行显式编号 ( [1]_ )或使用不带名称的自动编号脚注 ( [#]_ )。
效果：
5.2.7. 参考引用¶
对于有文献信息，添加引用，引用的信息就近添加，并使用有意义的编码，如 姓名+日期 。不使用脚注方式。
如：
Lorem ipsum [RefName]_ dolor sit amet.
.. [RefName] Book or article reference, URL or whatever.
效果：
Lorem ipsum [RefName] dolor sit amet.
Book or article reference, URL or whatever.