12.2. Sphinx文档修改要求#
Sphinx通过其自身语法要求进行项目内容关联，本身无目录结构明确要求。 为了方便团队内部修改，按以下要求来做一致性约束，避免一些问题。
关于图片与表格的交叉引用，Sphinx 目前有多种方式可实现。
目前建议通过给内容添加 :name: 属性来实现，代码、图片、表格等都可以使用这种方式，
使用 :name: 属性来定义引用名的引用方式有3种：
通过
引用名+下划线来实现引用，这样显示的文字为引用名，不一定合适；通过
:ref:`引用名`来引用，这样显示所引对像的标题；通过
:numref:`引用名`来引用，这样显示编码后的类型+数字序号。
12.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
备注
每次新添加了rst文档，需要添加到对应的地方。不必修改，由程序自动处理。
Sphinx项目每天会定时进行自动构建检查，如果有问题会相应生成 _error.txt 文件。
警告
如果在Sphinx项目中出现 _error.txt 文件，一定要检查，将问题修改过来。
章节名称#
章名称、节名称皆为三部分，用下划线分割。第三部分可以没有，为自动生成。
修改时主要把 sig 部分修改好，其为英文词汇，简要说明章节内容。
名称示例：
ch01_sig1_ka01
sec03_sig2_k0002
或：
ch01_sig1
sec03_sig2
12.2.2. 常规内容修改说明#
对于 Sphinx 文件（ .rst ） 常规内容，注意修改时断行的问题。
一般情况下一句不能太长。单句成行，在句号（ 。 ）后一般要断行，方便阅读。
如果单句太长 ，则在句中合适标点后，如逗号（ ， ），引号（ ： ），进行断行。
英文文本依照中文方式处理。
12.2.3. 单个文件中的标题使用#
对于已经存在的 .rst 文件，一般情况下不必修改标题。
如果进行修改，或新建 .rst 格式文件，使用不超过三级标题。
标题按如下使用方式约定：
一级标题：
===================
一级标题
===================
二级标题：
二级标题
==================================
三级标题：
三级标题
---------------------------------------
12.2.4. 图片#
警告
以下的代码一般为word自动转换的结果，使用这种方式无法以居中形式显示图片，所以要进行修改。
|logo|,使用"|宏名|"的形式替换文字。
.. |logo| image:: ./logo.png
它的原理是使用“||”类似宏的方式替换指令，使rst源码看起来更简洁，但不能居中显示。
图片原文件统一存储在引用文档所在的同级目录文件夹下。
添加图片使用 figure 指令，无特殊情况的话我们书籍图片要求使用居中方式显示，
还需要添加 alt 选项指定图片的描述，用于网站中使用，以便图片加载失败时显示文字。
不要使用bmp图片 ，bmp图片在生成pdf的时候会丢失，所以不要使用bmp格式的图片。
figure 添加图片时可以使用标题与legend。一般在使用时要加入引用。
图片还可以使用 width、heigh、scale等参数，但不推荐使用，设置过width、height参数的图片， 在页面可以点击查看原图。
图片引用#
语法：
.. figure:: ./logo.png
:alt: logo
:align: center
:name: OSGeoLogo
OSGeo Logo
效果：
图 12.2.1 OSGeo Logo#
引用的方式是使用 :name: 定义的名字加下划线 _ ，如：
OSGeoLogo_ ，效果 OSGeoLogo ;
或 :ref:`OSGeoLogo` ，效果 OSGeo Logo ；
或 :numref:`OSGeoLogo` , 效果 图 12.2.1 。
12.2.5. 使用CSV表格#
警告
表格与图片的处理， 关键要注意标题与引用。
为了方便修改，表格统一使用外部 CSV 格式的表格。
使用 numref 的方式进行引用，如 表 12.2.1 ，如：
.. csv-table:: 外部CSV表格示例
:file: deploy.csv
:widths: 5, 20
:header-rows: 1
:name: outcsv
引用的方式是使用 ``:name:`` 定义的名字加下划线 ``_`` ，如：
outcsv_
效果：
name |
备注 |
|---|---|
a1 |
igais/yubiao |
a2 |
|
a4 |
osgeo/jubook |
引用的方式是使用 :name: 定义的名字加下划线 _ ，如：
outcsv_ ， 效果 outcsv ；或使用更有意义的引用方式 :numref:`outcsv` , 效果 表 12.2.1 。
12.2.6. 数学表达式#
对于常见的各种文本，一般会使用图片的方式来呈现数学表达式。 在修改过程中需要将其修改为 Sphinx 支持的 Latex 方式的数学表达式。
具体使用方法参见 节 3.10 。 对于非数学类专业资料，一般使用 行内数学表达式 与 行间数学表达式 即可，不需要公式的交叉引用。
12.2.7. 脚注#
有关脚注 (ref )，使用显示编号 [1]_ 要标记脚注位置，并在文档底部的“脚注”标题后面添加脚注正文，如下所示：
示例
Lorem ipsum [1]_ dolor sit amet ... [2]_
**脚注**
.. [1] Text of the first footnote.
.. [2] Text of the second footnote.
效果
Lorem ipsum [1] dolor sit amet ... [2]
脚注
12.2.8. 参考引文#
对于整理的资料，一般情况下借用命名脚注的方式添加参考引文。
文献列表先进行整理，整理完成的文本在文档底部添加，或者放到单独一节中。
在每条文献前添加标识 ，注意使用有意义的编码，如 [姓名:年份] ，
如果是多个作者，姓名中间使用 - 分隔，如 [姓名1-姓名2:年份] 。
注意标识中不能出现空格，逗号。
一条文献一般放在一行，换行的话注意缩进。
然后在文本需要处添加文献引用。
备注
注意整理步骤，先对文献整理，添加添加文献引用； 在文档一般先出现文献引用，而文献的列表是在后面的。
示例
Lorem ipsum [RefName-Name2:1998]_ dolor sit amet.
这里是中文 [RefName3:2007] 示例。
**参考文献**
.. [RefName-Name2:1998] Book or article reference, URL or whatever.
.. [RefName3:2007] Book or article reference,
URL or whatever.
效果
Lorem ipsum [RefName-Name2:1998] dolor sit amet. 这里是中文 [RefName3:2007] 示例。
参考文献
Book or article reference, URL or whatever.
Book or article reference, URL or whatever.