来源

本文件是 Sphinx's reStructuredText Primer .

斯芬克斯重组文字底漆

介绍

RestructuredText文档只是一个带有一些标记的纯文本文件，用于指定文本的格式或语义。

标记有两种类型：

• 内联标记：例如， *the surrounding asterisks would mark this text as italics* ，像 this .

• 显式标记：用于需要特殊处理的文本，如脚注、表或一般指令。显式标记块始终以开头 .. 后面是空白。

段落

段落是REST文档中的基本块。

段落只是由一个或多个空行分隔的文本块。

缩进在静止状态下很重要，因此同一段落的所有行必须与缩进的相同级别保持对齐。

这是一种风格惯例。

每行最多可保留78个字符。记住，更改为下一行不会创建段落，除非文本块由空行分隔。

试着把每个短语放在不同的行中。它提高了可读性，方便了翻译过程。

记住，在HTML输出中将忽略连续的空白行。

引用的段落

引用段落是通过将其缩进到比周围段落多的位置来创建的：

Normal paragraph.

   Indented paragraph.

这是一种风格惯例。

每个缩进级别都用3个空格创建。不要使用标签。

换行符

行块是一种保留换行符的方法（相当于使用 Shift+Enter 在Microsoft Word或LibreOffice Writer中换行）：：

| These lines are
| broken exactly like in
| the source file.

小节

节是通过在节标题下加下划线（也可以选择在其上加下划线）和标点符号创建的：

This is a heading
=================

任何标点符号都可以用来定义节标题。下划线（和下划线）必须至少与文本本身一样长。节必须正确嵌套。

这是一种风格惯例。

在节标题中使用以下标点符号：

• # 对于零件

• * 对于章节

• = 对于章节（“标题1”）。

• - 对于小节（“标题2”）。

• ^ 对于子章节（“标题3”）。

• " 对于段落（“标题4”）。

请注意，当转换为 HTML 格式，节将自动转换为适当的标题标记（例如： <h2>Heading text</h2> ）

当转换为 ODT 或 DOCX ，将应用适当的标题样式。

内联标记

粗体、斜体、单空格

标记非常简单：

• 斜体使用一个星号： *text* （相当于使用 Ctrl+i 在Microsoft Word或LibreOffice Writer中）

• 使用两个星号进行强强调（粗体）： **text**

• 对文本文本文本使用反引号： ``text ` `

注意一些限制：

• 标记不能嵌套。例如，此标记错误： *italics with **bold** inside*

• 标记中的文本内容不能以空白开头或结尾。例如，此标记错误： * text*

• 标记必须用非单词字符（空格或标点）与周围文本分隔。使用反斜杠转义的空格来解决这个问题。例如： thisis\ *one*\ word 像这样呈现one 字。

• 如果星号或反引号出现在正在运行的文本中，并且可能与内联标记分隔符混淆，则必须用反斜杠对它们进行转义。

下标和上标

下标标记为 :sub:`subscript text '.上标用 :sup:`superscript text '.

这是小费。

解释文本周围需要空格或标点符号，但下标和上标通常不需要。可以使用反斜杠转义的空白；将从处理过的文档中删除空白：：

The chemical formula for molecular oxygen is O\ :sub:`2`.

为了提高文本的可读性，不鼓励使用反斜杠转义。如果可能，使用 替代品 取而代之的是：

The chemical formula for pure water is |H2O|.

.. |H2O| replace:: H\ :sub:`2`\ O

将所有替换项放在一起（例如在文件末尾）。

列表

项目符号列表

列表标记是自然的：只需在段落的开头放置一个星号并适当缩进：

*  This is a bulleted list.
*  It has two items, the second
   item uses two lines.

嵌套列表是可能的，但请注意，它们必须用空行与父列表项分隔：

* this is
* a list

  * with a nested list
  * and some sub-items

* and here the parent list continues

编号列表

编号列表也是如此；也可以使用 # 标志：：

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.

定义列表

定义列表创建如下：

term (up to a line of text)
   Definition of the term, which must be indented

   and can even consist of multiple paragraphs

next term
   Description.

这个 Sphinx 文档生成器为定义列表提供了更灵活的替代方法（请参见 词汇表 ）

词汇表

狮身人面像 ..glossary:: 指令包含一个REST定义列表，如带有术语和定义的标记。

请参见以下示例：

.. glossary::

   environment
      A structure where information about all documents under the root is
      saved, and used for cross-referencing.  The environment is pickled
      after the parsing stage, so that successive runs only need to read
      and parse new and changed documents.

   source directory
      The directory which, including its subdirectories, contains all
      source files for one Sphinx project.

然后将在交叉引用中使用这些定义 :term: 角色。例如：：

The :term:`source directory` for this project is ...

与常规定义列表不同，术语表支持 倍数 术语中允许每个条目的术语和内联标记。您可以链接到所有术语。例如：：

.. glossary::

   term 1
   term 2
      Definition of both terms.

当词汇表排序时，第一个术语决定排序顺序。

要自动对词汇表排序，请包含以下标志：

.. glossary::
   :sorted:

字段列表

字段列表是类似于数据库记录（标签和数据对）的两列类表结构。例如：：

:Date: 2001-08-16
:Version: 1
:Authors: - Me
          - Myself
          - I
:Indentation: Since the field marker may be quite long, the second
   and subsequent lines of the field body do not have to line up
   with the first line, but they must be indented relative to the
   field name marker, and they must line up with each other.
:Parameter i: integer

这是一种风格惯例。

在此项目中，字段列表用于在每个文档中包含元数据。

基本 `Dublin Core`_ 元数据字段应该包含在每个文档的最开始部分（如文本文件的标题），如下所示：

.. metadata-placeholder

:DC.Title:
   Document title
:DC.Creator:
   Author
:DC.Date:
   Date yyyy-mm-dd
:DC.Description:
   Abstract
:DC.Language:
   en
:DC.Format:
   text/x-rst
:DC.Rights:
   Access rights
:DC.RightsHolder:
   Copyright.

注意，这些元数据字段名不会被sphinx解析器自动识别，因此文本本身在HTML页面中不可见（例如）。元数据字段与 文档属性 A中的字段 DOCX 文件或 ODT 文件。

docutils 识别多个书目字段（例如 docinfo ， author ， authors ， organization ， contact ， version ， status ， date ， copyright ， field ， topic ）

这是一个高级主题

斯芬克斯识别了一些元数据文件。例如：

• :tocdepth: 指示文件的sphinx侧边栏目录中的最大级别数。

• :orphan: 指示即使文件未包含在 .. toctree:: 指示，斯芬克斯不应发出警告。

桌子

RestructuredText标记支持两种基本类型的表。为了 网格表 你必须自己绘制细胞网格。它们看起来像这样：

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+

简单表 更容易编写，但有限：它们必须包含多行，并且第一列不能包含多行。它们看起来像这样：

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

这是小费。

这些是表的基本类型，相当笨拙。还提供（而且更容易使用）的 special tables 即列表表和csv表。

安 exceltable_ 扩展也可用于 Sphinx, 允许包含 XLS 将电子表格或其中的一部分放入一个REST文档中。

超链接

外部链接

使用 `link text <http://example.com/>`_ 对于内联Web链接。如果链接文本应该是网址，则根本不需要特殊的标记，解析器会在普通文本中查找链接和邮件地址（不带标记）。

您还可以分离链接和目标定义，如下所示：

This is a paragraph that contains `a link`_.

.. _a link: http://example.com/

这是小费。

不鼓励使用内联Web链接，以提高其余文本的可读性。

简单链接（例如到机构网站、软件网站等）应保存在文本文件的末尾（这只是简化编辑过程和更新和验证链接的一种方法）。

内部链接

为了支持对任何文档中任意位置的交叉引用，使用标准的REST标签。为此，标签名称在整个文档中必须是唯一的。有两种方法可以引用标签：

• 如果将标签直接放置在节标题之前，可以使用 :ref:`label-name '.例子：：

  .. _my-label-ref:
  
  Section to cross-reference
  --------------------------
  
  This is the text of the section.
  
  In the end of this phrase is a reference to the section title, see :ref:`my-label-ref`.
  

  这个 :ref: 然后，角色将生成指向该节的链接，链接标题为“节到交叉引用”。当节和引用位于不同的源文件中时，这也同样有效。

  自动标签也适用于 figures ：：

  .. _my-figure-ref:
  
  .. figure:: my-image.png
  
     My figure caption
  

  类似于 :ref:`my-figure-ref `将插入对带有链接文本“我的图形标题”的图形的引用。

  同样适用于 tables 使用 table 指令。

• 仍可以引用节标题之前未放置的标签，但必须使用以下语法为链接提供文本： :ref:`Link text <label-name> '.

使用 :ref: 建议使用标准的重构文本链接到节（如 `Section title`_ ）因为它跨文件工作，当节标题被更改时，以及对于所有支持交叉引用的构建器。

源代码

文字代码块是通过在段落结尾加上特殊标记来引入的。 :: . 文本块必须缩进（和所有段落一样，用空行与周围段落分隔）：：

This is a normal text paragraph. The next paragraph is a code sample::

   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.

处理 :: 标记很智能：

• 如果它是以自己的段落出现的，则该段落完全不在文档中。

• 如果前面有空白，则删除标记。

• 如果前面有非空白，则标记将被单个冒号替换。

这样，上面示例第一段中的第二句话将被表示为“下一段是代码示例：”。

显式标记

对于大多数需要特殊处理的结构（如脚注、特别突出显示的段落、注释和一般指令），在RestructuredText中使用显式标记。

显式标记块以一行开头 .. 后面是空白，最后是同一缩进级别的下一段。（在显式标记和普通段落之间需要有一个空行。这听起来可能有点复杂，但当你写的时候，它就足够直观了。）

指令

指令是显式标记的通用块。

指令内容位于空行之后，并相对于指令开头缩进。

基本上，指令由名称、参数、选项和内容组成。

看看这个例子：

.. contents:: This is my Table of Contents
   :depth: 2

指令以开头 .. 后面是一个空白。指令的名称是 contents （它创建一个目录）。这个指令接受一个参数：目录的标题（“这是我的目录”）。选择权 depth 指定在目录中收集的节级别数。

选项在参数后面的行中给出，并由冒号指示。选项必须缩进到与指令内容相同的级别。

Docutils 支持以下指令：

• 警告： attention ， caution ， danger ， error ， hint ， important ， note ， tip ， warning 和一般的 admonition . （仅适用于大多数主题样式 note 和 warning 特别是。）

• 图像：

  • image -见 images 剖面；

  • figure -带有标题和可选图例的图像。

• 附加车身元件：

  • contents <table-of-contents> -仅当前文件中节的本地目录；

  • rubric -与文件章节无关的标题，不包括在任何目录中；

  • topic 和 sidebar -特别突出的身体元素；

  • epigraph -具有可选属性行的块引号；

  • container -具有自定义类的容器，用于生成外部 ``<div> ``在HTML输出中。

• 特殊表格 ：

  • table -有标题的桌子；

  • csv-table -由逗号分隔值生成的表；

  • list-table -从列表列表生成的表。

• 特别指示：

  • include -包括来自另一个文件的RestructuredText；

  • raw -包括原始目标格式标记，如 Latex ；

  • class -为下一个元素分配一个类属性。

目录

要在给定文档中包含目录，请使用指令 contents . 以下示例创建最多两个级别（位于其所在级别之下）的本地目录：

Part II
#######

Chapter 1
*********

.. contents::
   :depth: 2
   :local:

Heading 1
=========

这个 toctree 指令创建从多个文件收集信息的目录。下面的示例从各种文档的各个部分（最多3个级别）创建一个目录。这个 :glob: 选项允许包含“chapter2”文件夹中的所有文档（根据其名称排序）：：

.. toctree::
   :glob:
   :maxdepth: 3

   preamble
   chapter1/part1
   chapter1/conclusion
   chapter2/*
   references

注解

当从默认模板构建HTML页面时， <div class="sphinxsidebar"> 创建了一个包含指向文档节的链接的“目录”。可以控制边栏中的级别数。例如，放置 :tocdepth: 3 在文件的开头，将级别数限制为3。

图像

rest支持image指令，使用方式如下：

.. image:: gnu.png
   (options)

给定的文件名（此处 gnu.png ）必须是相对于源文件的，或者是绝对的（这意味着它们是相对于顶级源目录的）。

例如，文件 sketch/spam.rst 可以参考图像 images/spam.png 作为 ../images/spam.png 或作为 /images/spam.png .

图像大小选项 (width 和 height ）应在点中指定 (pt ，因为这将最好支持不同格式的输出 (HTML ， LaTeX ）

数字

A figure 由图像数据（包括图像选项）、可选标题（单个段落）和可选图例（任意正文元素）组成：

.. figure:: picture.png
   :scale: 50 %
   :alt: map to buried treasure

   This is the caption of the figure (a simple paragraph).

   The legend consists of all elements after the caption.  In this
   case, the legend consists of this paragraph and the following
   table:

   +-----------------------+-----------------------+
   | Symbol                | Meaning               |
   +=======================+=======================+
   | .. image:: tent.png   | Campground            |
   +-----------------------+-----------------------+
   | .. image:: waves.png  | Lake                  |
   +-----------------------+-----------------------+
   | .. image:: peak.png   | Mountain              |
   +-----------------------+-----------------------+

标题段落前和图例前必须有空行。若要指定没有标题的图例，请使用空注释 (.. ）代替标题。

特殊表格

这个 table 指令将标题与下表关联：

.. table:: User list

   ==========  =========
   First name  Last name
   ==========  =========
   John        Doe
   Jane        Dove
   ==========  =========

A list-table 从统一的两级项目符号列表创建：

.. list-table:: User list
   :header-rows:1

   *  - First name
      - Last name
   *  - John
      - Doe
   *  - Jane
      - Dove

A csv-table 由逗号分隔的值（在文档或外部文件中）创建：

.. csv-table:: User list
   :header:"First name","Last name"

   "John","Doe"
   "Jane","Dove"

另一个例子 csv-table ，使用和外部文件：：

.. csv-table:: Table 1 - Legend of the table goes here...
   :header-rows: 1
   :stub-columns: 1
   :file: ../tables/table1.csv

安 exceltable 也可以使用：

.. exceltable:: Table 1 - Legend of the table goes here...
   :file: ../tables/tables.xls
   :sheet: table1
   :selection: A1:C20
   :header: 1

使用Excel表格需要额外的模块 sphinxcontrib.exceltable 这是对sphinx的扩展，它在sphinx文档中添加了对电子表格或其中一部分的支持。可以使用PIP安装：

pip install sphinxcontrib-exceltable

然后是项目 conf.py 需要更新文件：：

# Add ``sphinxcontrib.exceltable`` into extension list
extensions = ['sphinxcontrib.exceltable']

另一种选择是xmltable（https://pythonhosted.org/rusty/xmltable.html）。

脚注

对于脚注，请使用 [#name]_ 标记脚注位置，并将脚注正文添加到文档底部的“footnotes”标题后面，如：

Lorem ipsum [#first-footnote-name]_ dolor sit amet [#second-footnote-name]_

.. rubric:: Footnotes

.. [#first-footnote-name] Text of the first footnote.
.. [#fsecond-footnote-name] Text of the second footnote.

你也可以明确地给脚注编号。 ([1]_ ）或者使用不带名称的自动编号脚注 ([#]_ ）

这是小费。

为了便于编辑，自动编号的脚注应 not 使用。相反，使用简短的描述性名称（这样可以简化交叉引用）。

引文

支持标准的REST引用：：

Lorem ipsum [Ref]_ dolor sit amet.

.. [Ref] Book or article reference, URL or whatever.

引文用法类似于脚注用法，但标签不是数字或以开头 # .

当使用 Sphinx 文档生成器，引用是“全局的”，这意味着每个引用都可以从任何.rst文件中引用。在这种情况下，可以创建一个单独的文件（例如 references.rst 文件）。

这是小费。

见 斯芬克斯文献引文管理 更多信息。

替代品

REST支持“替换”，即文本中引用的文本和/或标记 |name| . 它们被定义为带有显式标记块的脚注，如下所示：

.. |name| replace:: replacement *text*

或者：

.. |caution| image:: warning.png
             :alt: Warning!

如果要对所有文档使用某些替换，请将它们放入单独的文件（例如 substitutions.txt ）并将其包含到所有要在其中使用它们的文档中，使用 include 指令。

确保使用与其他源文件不同的文件扩展名，以避免Sphinx将其作为独立文档查找。例如，使用 .rst 源文件的文件扩展名，以及 .txt 要包含的文件的文件扩展名。

这是小费。

这在技术文档（如用户手册）中很有用，在技术文档中，可以为界面元素（菜单、消息等）的每个本地化版本构建替换文件，以确保文档翻译与软件的用户界面的一致性。

警告。

替换在指令内（或在指令选项内）不起作用。

不要试图通过谷歌搜索来寻求解决方案。这是一个设计限制：RST标记不能嵌套。期间。

评论

每个不是有效标记构造的显式标记块都被视为注释。例如：：

.. This is a comment.

可以在注释开始后缩进文本以形成多行注释：：

..
   This whole indented block
   is a comment.

   Still in the comment.

这是一种风格惯例。

注释还可以用作占位符来标记文档中的位置。例如：

• 这个 .. links-placeholder 可以在文档末尾标记超链接存放的位置；

• 这个 .. metadata-placeholder 可以标记文档元数据（作者、日期等）在文档开头存放的位置。