sphinx基础语法：列表

最新推荐文章于 2025-06-10 09:04:41 发布

原创最新推荐文章于 2025-06-10 09:04:41 发布 · 498 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#sphinx

工具专栏收录该内容

4 篇文章

订阅专栏

本文详细介绍了reStructuredText中的四种主要列表类型（无序、枚举、定义和字段列表），以及选项列表的规则，包括POSIX、DOS/VMS风格和reStructuredText特有的语法。

1.无序列表

以“*”、“+”、“-”、“•”、“‣”或“⁃”开头的文本块，后跟空格，是项目符号列表项（又称“无序”列表项）。

示例：

- 这是第一个项目列表项。第一个列表项目上方的空白行是必需的;列表项之间的空白行(如本段下面)是可选的。
- 这是清单第二项的第一段。
  
  这是清单第二项的第二段。这一段上面的空白行是必需的。这个段落的左边缘与上面的段落对齐，都相对于项目符号缩进。

  - 这是一个子列表。项目符号与上面文本块的左边缘对齐。子列表是一个新列表，因此需要在上面和下面都有空白行。

- 这是主表的第三项。

效果：

在这里插入图片描述

2.枚举列表

枚举列表（又称“有序”列表）类似于项目符号列表，但使用枚举器而不是项目符号。枚举器由枚举序列成员和格式，后跟空格。可识别以下枚举序列：

阿拉伯数字： 1， 2， 3， …（无上限）。
大写字母字符：A、B、C、…、Z。
小写字母字符：A、B、C、…、Z。
大写罗马数字：I、II、III、IV、…、MMMMCMXCIX （4999）。
小写罗马数字：i，ii，iii，iv，…，mmmmcmxcix （4999）。

此外，自动枚举器“#”可用于自动枚举列表。自动枚举列表可能以显式开头枚举，用于设置序列。完全自动枚举的列表使用阿拉伯数字，以 1 开头。

可识别以下格式设置类型：

后缀为句点：“1.”、“A.”、“a.”、“I.”、“i.”。
用括号括起来：“（1）”、“（A）”、“（a）”、“（I）”、“（i）”。
后缀为右括号：“1）”、“A）”、“a）”、“I）”、“i）”。

解析枚举列表时，将在以下任何时间启动新列表：

遇到格式不同的枚举器，并且序列类型作为当前列表（例如“1.”，“（a）”产生两个单独的列表）。
枚举器不按顺序排列（例如，“1.”，“3.”产生两个单独的列表）。

建议第一个列表项的枚举器序数-1（“1”、“A”、“a”、“I”或“i”）。虽然其他起始值将被识别，输出格式可能不支持它们。一个将为任何列表开头生成 1 级 [信息] 系统消息使用非序数 1 枚举器。

使用罗马数字的列表必须以“I”/“i”或多字符值，例如“II”或“XV”。任何其他单字符罗马数字（“V”、“X”、“L”、“C”、“D”、“M”）将是解释为字母表中的字母，而不是罗马数字。同样，使用字母表字母的列表可能不以 “I”/“i”，因为它们被识别为罗马数字 1。

检查每个枚举列表项的第二行的有效性。这是为了防止普通段落被误读解释为列表项，当它们碰巧以文本开头时与枚举器相同。例如，此文本被解析为普通段落：

A. 我真是一个帅气、聪明
且180cm男孩

但是，如果该段仅由一行。此文本被分析为枚举列表项：

A. 我真是一个帅气、聪明且180cm男孩

谨慎！

如果单行段落以与枚举器相同的文本开头（“A.”、“1.”、“（b）”、“I）”等），第一个字符必须是转义符以便将该行解析为普通段落：

\A. 我真是一个帅气、聪明且180cm男孩

或者，你也可以转义分隔符

A\. 我真是一个帅气、聪明且180cm男孩

或者在首字母后使用文字无中断空格。

示例：

1. 这是一个有序列表。
2. 使用阿拉伯数字、字母、罗马数字来表示。

a. 这是一个有序列表。
b. 使用阿拉伯数字、字母、罗马数字来表示。

I. 这是一个有序列表。
II. 使用阿拉伯数字、字母、罗马数字来表示。

效果：

在这里插入图片描述

3.定义列表

每个定义列表项都包含一个术语、可选分类器和定义。

术语是一个简单的单行单词或短语。转义前导连字符以防止识别为选项列表项。
可选分类器可以在同一行上跟在术语后面，每个分类器之后内联 “ ： ”（空格、冒号、空格）。内联标记在识别分类器分隔符之前的术语行。分隔符仅当它出现在任何内联标记之外时，才会被识别。
定义是相对于术语缩进的块，可以包含多个段落和其他正文元素。可能没有术语行和定义块之间的空行（此区分定义列表和块引号）。空行是在第一个定义列表项之前和之后是必需的，但是介于两者之间是可选的。

示例：

term 1
    Definition 1.

term 2
    Definition 2, paragraph 1.

    Definition 2, paragraph 2.

term 3 : classifier
    Definition 3.

term 4 : classifier one : classifier two
    Definition 4.

\-term 5
    Without escaping, this would be an option list item.

效果：

在这里插入图片描述

定义列表可以以多种方式使用，包括：

作为字典或词汇表。该术语是单词本身，一个分类器可用于指示术语（名词，动词等），定义如下。
描述程序变量。术语是变量名，a 分类器可用于指示变量的类型（字符串，整数等），并且定义描述了变量在程序。定义列表的这种用法支持分类器 Grouch的语法，一个描述和执行Python的系统对象架构。

4.字段列表

字段列表用作扩展语法的一部分，例如选项用于指令，或类似数据库的记录，用于进一步加工。它们也可用于两列表格状类似于数据库记录的结构（标签和数据对）。 reStructuredText 的应用可以识别字段名称和在某些上下文中转换字段或字段主体。

字段列表是从字段名称到字段正文的映射，以 RFC822 标头为模型。字段名称可以包含任何字符，但字段名称中的冒号（“：”）必须进行反斜杠转义后跟空格时。

内联标记在字段名称中解析，但在以下情况下必须小心在字段名称中使用具有显式角色的解释文本：角色必须是解释文本的后缀。字段名称为进一步处理或转换时不区分大小写。该领域名称，以及单个冒号前缀和后缀，共同构成字段标记。字段标记后跟空格和现场正文。字段正文可能包含多个主体元素，相对于字段标记缩进。字段后的第一行名称标记确定字段正文的缩进。

示例：

: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

效果：

在这里插入图片描述

多词字段名称中单个单词的解释为直到应用程序。应用程序可以指定语法字段名称。例如，可以处理第二个和后续单词作为“论据”，引用的短语可以被视为单个论据，并且可以添加对“名称=值”语法的直接支持。

标准 RFC822 标头不能用于此构造，因为它们是模棱两可的。一个单词，后跟一个冒号，开头的行在书面文本中很常见。但是，在明确定义的上下文中例如，当字段列表总是出现在文档（PEP 和电子邮件），标准 RFC822 标头可以是使用。

5.选项列表

reStructuredText 可识别几种类型的选项：

短 POSIX 选项由一个破折号和一个选项字母组成。
长 POSIX 选项由两个破折号和一个选项词组成;一些系统使用单个破折号。
旧的GNU风格的“加号”选项包括一个加号和一个选项字母（“加号”选项现已弃用，不鼓励使用）。
DOS/VMS 选项由斜杠和选项字母或单词组成。

请注意，POSIX 样式和 DOS/VMS 样式选项都可能是由DOS或Windows软件使用。这些和其他变体是有时混合使用。以上名称已被选中用于仅方便。

短 POSIX 和长 POSIX 选项的语法基于由 Python 的 getopt.py 模块支持，该模块实现了一个选项解析器类似于 GNU libc getopt_long（）函数，但有一些限制。有许多变体选项系统，并且 reStructuredText 选项列表不支持所有这些选项。

虽然长POSIX和DOS / VMS选项词可能被允许在命令行，reStructuredText 选项列表不显示或支持这使用任何特殊语法。完整的选项词应该是给定，并辅以有关截断的说明（如果适用）。

选项后面可以跟一个参数占位符，其角色和应在说明文本中解释语法。空格或等号都可以用作长选项和选项参数占位符; 短选项（仅限“-”或“+”前缀）使用空格或省略分隔符。选项参数可以采用以下两种形式之一：

以字母（[a-zA-Z]）开头，随后由字母、数字、下划线和连字符（[a-zA-Z0-9_-]）。
以开角括号（<）开头，以近角括号（>）;除尖括号以外的任何字符内部允许。

可以列出多个选项“同义词”，共享一个描述。它们必须用逗号空格分隔。

选项和描述（也可以从下一行开始）。说明可能包含多个正文元素。选项标记后的第一行确定描述。与其他类型的列表一样，需要空行在第一个选项列表项之前和最后一个选项列表项之后，但可选在选项条目之间。

示例：

-a         Output all.
-b         Output both (this description is
           quite long).
-c arg     Output just arg.
--long     Output all day long.

-p         This option has two paragraphs in the description.
           This is the first.

           This is the second.  Blank lines may be omitted between
           options (as above) or left in (as here and below).

--very-long-option  A VMS-style option.  Note the adjustment for
                    the required two spaces.

--an-even-longer-option
           The description can also start on the next line.

-2, --two  This option has two variants.

-f FILE, --file=FILE  These two options are synonyms; both have
                      arguments.

/V         A VMS/DOS-style option.

效果：

在这里插入图片描述