Sphinx RST风格指南

此页包含使用Sphinx和structuredtext的语法规则、提示和技巧。有关详细信息，请参见 comprehensive guide to reStructuredText 以及 Sphinx reStructuredText Primer .

基本标记

重构的文本文档是用纯文本编写的。不需要复杂的格式，就可以像任何纯文本文档一样简单地编写文档。有关基本格式，请参见下表：

Format	Syntax	Output
斜体字	`italics` （单星号）	斜体字
大胆的	`bold` （双星号）	bold
单空间	`` `` 单空格```（双反引号）	`monospace`

警告

基本标记的使用是 不推荐 ! 尽可能使用sphinx内联指令在逻辑上标记命令、参数、选项、输入和文件。通过一致地使用指令，可以适当地设置这些项的样式。

列表

有两种类型的列表，项目符号列表和编号列表。一个 项目符号列表 如下所示：

物品
另一项
又一个项目

这是通过以下代码完成的：

* An item
* Another item
* Yet another item

A 编号列表 如下所示：

第一项
第二项
第三项

这是通过以下代码完成的：

#. First item
#. Second item
#. Third item

请注意，数字是自动生成的，便于添加/删除项目。

列出表格

项目列表有时会很麻烦，很难遵循。在处理一长串项目时，请使用列表表。例如，要讨论选项列表，请创建如下所示的表：

形状	描述
正方形	等长90度角四边
矩形	四面，90度角

使用以下代码完成此操作：

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Shapes
     - Description
   * - Square
     - Four sides of equal length, 90 degree angles
   * - Rectangle
     - Four sides, 90 degree angles

页面标签

确保每个页面都有与文件名匹配的标签。 例如，如果页面名为 foo_bar.rst 那么页面应该有标签：

..  _foo_bar:

然后，其他页面可以使用以下代码链接到该页面：

:ref:`foo_bar`

链接

链接到其他页面不应该被命名为“这里”。Sphinx通过自动插入链接文档的标题使这一操作变得简单。

坏的: 可以找到有关链接的更多信息 here .
很好: 有关详细信息，请参阅链接 .

插入指向外部网站的链接：

`Text of the link <http://example.com>`__

结果链接如下所示： Text of the link

警告

很容易有两个具有相同文本的链接，从而导致以下错误：

**(WARNING/2) Duplicate explicit target name:foo**

为了避免这些警告，请使用double __ 生成匿名链接。

小节

使用节来分解长页并帮助Sphinx生成目录。

================================================================================
Document title
================================================================================

First level
-----------

Second level
++++++++++++

Third level
***********

Fourth level
~~~~~~~~~~~~

注意事项和警告

当一段文字从正文中脱颖而出时，Sphinx有两个这样的框，注释和警告。它们的功能相同，只是颜色不同。但是，您应该谨慎地使用注释和警告，因为对所有内容添加强调会降低强调的效果。

下面是一个注释示例：

备注

这是一张便条。

此便笺由以下代码生成：

.. note:: This is a note.

类似地，下面是一个警告示例：

警告

当心龙。

此警告由以下代码生成：

.. warning:: Beware of dragons.

图像

尽可能将图像添加到文档中。图片，如屏幕截图，是一种非常有用的方式，使文档易于理解。制作屏幕截图时，尽量删掉不必要的内容（浏览器窗口、桌面等）。避免缩放图像，因为 Shpinx 主题会自动调整大图像的大小。在图片下面加上标题也很有帮助

.. figure:: image.png
   :align: center

   *Caption*

在本例中，图像文件与源页面位于同一目录中。如果不是这样，可以在上面的命令中插入路径信息。根 / 是 conf.py 文件：

.. figure:: /../images/gdalicon.png

外部文件

文本片段、大量可下载代码，甚至zip文件或其他二进制源都可以作为文档的一部分包含在内。

若要包含指向示例文件的链接，请使用 download 指令：

:download:`An external file <example.txt>`

此代码的结果将生成到 external file

To include the contents of a file, use literalinclude directive:

Example of :command:`gdalinfo` use:

.. literalinclude:: example.txt

实例 gdalinfo 使用：

Driver: GTiff/GeoTIFF
Size is 512, 512
Coordinate System is:
PROJCS["NAD27 / UTM zone 11N",
    GEOGCS["NAD27",
        DATUM["North_American_Datum_1927",
            SPHEROID["Clarke 1866",6378206.4,294.978698213901]],
        PRIMEM["Greenwich",0],
        UNIT["degree",0.0174532925199433]],
    PROJECTION["Transverse_Mercator"],
    PARAMETER["latitude_of_origin",0],
    PARAMETER["central_meridian",-117],
    PARAMETER["scale_factor",0.9996],
    PARAMETER["false_easting",500000],
    PARAMETER["false_northing",0],
    UNIT["metre",1]]
Origin = (440720.000000,3751320.000000)
Pixel Size = (60.000000,-60.000000)
Corner Coordinates:
Upper Left  (  440720.000, 3751320.000) (117d38'28.21"W, 33d54'8.47"N)
Lower Left  (  440720.000, 3720600.000) (117d38'20.79"W, 33d37'31.04"N)
Upper Right (  471440.000, 3751320.000) (117d18'32.07"W, 33d54'13.08"N)
Lower Right (  471440.000, 3720600.000) (117d18'28.50"W, 33d37'35.61"N)
Center      (  456080.000, 3735960.000) (117d28'27.39"W, 33d45'52.46"N)
Band 1 Block=512x16 Type=Byte, ColorInterp=Gray

这个 literalinclude 指令有语法突出显示、行号和仅提取片段的选项：

Example of :command:`gdalinfo` use:

.. literalinclude:: example.txt
   :language: txt
   :linenos:
   :emphasize-lines: 2-6
   :start-after: Coordinate System is:
   :end-before: Origin =

参考文件和路径

使用以下语法引用文件和路径：

:file:`myfile.txt`

这将输出： myfile.txt .

您可以用同样的方式引用路径：

:file:`path/to/myfile.txt`

这将输出： path/to/myfile.txt .

对于Windows路径，请使用双反斜杠：

:file:`C:\\myfile.txt`

这将输出： C:\myfile.txt .

如果要引用非特定路径或文件名：

:file:`{your/own/path/to}/myfile.txt`

这将输出： {your/own/path/to}/myfile.txt

Reference code

To reference a class:

:cpp:class:`MyClass`

To reference a method or function:

:cpp:func:`MyClass::MyMethod`
:cpp:func:`MyFunction`

Reference configuration options

To reference a configuration option, such as GDAL_CACHEMAX, use:

:decl_configoption:`OPTION_NAME`

参考命令

引用命令（例如 gdalinfo )使用以下语法：

:program:`gdalinfo`

使用 option 命令行选项的指令：

.. option:: -json

   Display the output in json format.

使用 describe 记录创建参数：

.. describe:: WORLDFILE=YES

   Force the generation of an associated ESRI world file (with the extension .wld).