PEP 258 – Docutils 设计规范

作者:: David Goodger <goodger at python.org>
讨论邮件列表:: Doc-SIG 邮件列表
状态:: 已拒绝
类型:: 标准跟踪
依赖:: 256, 257
创建日期:: 2001年5月31日
更新历史:: 2001年6月13日

拒绝通知

虽然这可以作为现在独立的 docutils 的一个有趣的项目设计文档，但它不再计划包含在标准库中。

摘要

此 PEP 文档记录了 Docutils（一个 Python 文档字符串处理系统 (DPS)）的设计问题和实现细节。DPS 的基本原理和高级概念在 PEP 256，“文档字符串处理系统框架”中进行了记录。另请参阅 PEP 256 以获取“文档字符串 PEP 路线图”。

Docutils 正在以模块化的方式进行设计，以便其任何组件都可以轻松替换。此外，Docutils 不仅限于处理 Python 文档字符串；它还在多种上下文中处理独立文档。

此 PEP 不需要对核心 Python 语言进行任何更改。其交付内容包括一个标准库包及其文档。

规范

Docutils 项目模型

项目组件和数据流

                 +---------------------------+
                 |        Docutils:          |
                 | docutils.core.Publisher,  |
                 | docutils.core.publish_*() |
                 +---------------------------+
                  /            |            \
                 /             |             \
        1,3,5   /        6     |              \ 7
       +--------+       +-------------+       +--------+
       | READER | ----> | TRANSFORMER | ====> | WRITER |
       +--------+       +-------------+       +--------+
        /     \\                                  |
       /       \\                                 |
 2    /      4  \\                             8  |
+-------+   +--------+                        +--------+
| INPUT |   | PARSER |                        | OUTPUT |
+-------+   +--------+                        +--------+

每个组件上方的数字表示文档数据所经过的路径。读取器和解析器之间以及转换器和写入器之间的双线表示沿这些路径发送的数据应该是标准的（纯净且未扩展的）Docutils 文档树。单线表示内部树扩展或完全无关的表示是可能的，但必须在两端都支持。

docutils.core 模块包含一个“发布者”外观类和几个便捷函数：“publish_cmdline()”（用于命令行前端），“publish_file()”（用于带有文件式 I/O 的编程使用）和“publish_string()”（用于带有字符串 I/O 的编程使用）。发布者类封装了 Docutils 系统的高级逻辑。Publisher.publish() 方法控制发布者类对处理的整体责任

设置内部设置（可能包括配置文件和命令行选项）和 I/O 对象。
调用读取器对象以从源输入对象读取数据，并使用解析器对象解析数据。返回一个文档对象。
通过附加到文档的转换器对象设置并应用转换。
调用写入器对象，它将文档转换为最终输出格式，并将格式化后的数据写入目标输出对象。根据输出对象，输出可能从写入器返回，然后从 publish() 方法返回。

使用组件名称调用“发布”函数（或实例化“发布者”对象）将导致默认行为。对于自定义行为（自定义组件设置），首先创建自定义组件对象，并将它们传递给发布者或 publish_* 便利函数。

读取器

读取器了解输入上下文（数据来自哪里），将整个输入或离散的“块”发送到解析器，并提供上下文以将块重新绑定到一个连贯的整体。

每个读取器都是一个模块或包，导出一个具有“读取”方法的“读取器”类。基本“读取器”类可以在 docutils/readers/__init__.py 模块中找到。

大多数读取器都需要被告知使用哪个解析器。到目前为止（参见下面的示例列表），只有 Python 源代码读取器（“PySource”；仍在开发中）能够自行确定解析器。

职责

从源 I/O 获取输入文本。
将输入文本传递给解析器，以及一个新的文档树根节点。

示例

独立（原始/纯文本）：只需读取文本文件并处理它。读取器需要被告知使用哪个解析器。
“独立读取器”已在 docutils.readers.standalone 模块中实现。
Python 源码：请参阅下面的 Python 源码读取器。此读取器目前正在 Docutils 沙盒中开发。
电子邮件：RFC 822 标头、引用摘录、签名、MIME 部分。
PEP：RFC 822 标头、“PEP xxxx”和“RFC xxxx”转换为 URI。“PEP 读取器”已在 docutils.readers.pep 模块中实现；请参阅 PEP 287 和 PEP 12。
Wiki：将“wiki 链接”的全局引用查找合并到转换中。（仅限驼峰式大小写或不受限制？）延迟缩进？
网页：作为独立文件，但将元字段识别为元标签。是否支持某种类型的模板？（在 <body> 之后，在 </body> 之前？）
FAQ：结构化的“问题和答案”结构。
复合文档：将章节合并成一本书。主清单文件？

解析器

解析器分析其输入并生成 Docutils 文档树。它们不知道也不关心数据的来源或目标。

每个输入解析器都是一个模块或包，导出一个具有“解析”方法的“解析器”类。基本“解析器”类可以在 docutils/parsers/__init__.py 模块中找到。

职责：给定原始输入文本和文档树根节点，通过解析输入文本填充文档树。

示例：到目前为止，唯一实现的解析器是用于 reStructuredText 标记语言的解析器。它在 docutils/parsers/rst/ 包中实现。

其他解析器的开发和集成是可能的，并且鼓励这样做。

转换器

位于 docutils/transforms/__init__.py 中的转换器类存储转换并将它们应用于文档。转换器对象附加到每个新的文档树。发布者调用 Transformer.apply_transforms() 将所有存储的转换应用于文档树。转换将文档树从一种形式更改为另一种形式，添加到树中或修剪它。转换解析引用和脚注编号，处理解释文本并执行其他上下文相关的处理。

一些转换特定于组件（读取器、解析器、写入器、输入、输出）。标准的特定于组件的转换在组件类的 default_transforms 属性中指定。读取器完成处理后，发布者使用组件列表调用 Transformer.populate_from_components()，并且所有默认转换都将被存储。

每个转换都是 docutils/transforms/ 包中某个模块中的一个类，是 docutils.transforms.Transform 的子类。转换类都具有一个 default_priority 属性，转换器使用该属性按顺序（从低到高）应用转换。在将转换添加到转换器对象时，可以覆盖默认优先级。

转换器职责

按优先级顺序将转换应用于文档树。
存储组件类型名称（'读取器'、'写入器'等）到组件对象的映射。某些转换（例如“组件。过滤器”）使用这些映射来确定适用性。

转换职责

就地修改文档树，或者纯粹地将一种结构转换为另一种结构，或者基于文档树和/或外部数据添加新的结构。

转换示例（在 docutils/transforms/ 包中）

frontmatter.DocInfo：文档元数据（书目信息）的转换。
references.AnonymousHyperlinks：将匿名引用解析到相应的目标。
parts.Contents：为文档生成目录。
document.Merger：将多个填充的文档树合并为一个。（尚未实现或完全理解。）
document.Splitter：将文档拆分为子文档的树结构，可能按节进行拆分。它必须适当地转换引用。（既未实现也未完全理解。）
components.Filter：包含或排除依赖于特定 Docutils 组件的元素。

写入器

写入器生成最终输出（HTML、XML、TeX 等）。写入器将内部文档树结构转换为最终数据格式，可能首先运行特定于写入器的转换。

当文档到达写入器时，它应该处于最终形式。写入器的工作仅仅是（并且只是）将 Docutils 文档树结构转换为目标格式。可能需要一些小的转换，但它们应该是本地且特定于格式的。

每个写入器都是一个模块或包，导出一个具有“写入”方法的“写入器”类。基本“写入器”类可以在 docutils/writers/__init__.py 模块中找到。

职责

将文档树转换为特定的输出格式。
- 将引用转换为特定于格式的形式。
将转换后的输出写入目标 I/O。

示例

XML：各种形式，例如
- Docutils XML（内部文档树的表达，实现为 docutils.writers.docutils_xml）。
- DocBook（正在 Docutils 沙盒中实现）。
HTML（XHTML 实现为 docutils.writers.html4css1）。
PDF（ReportLabs 接口正在 Docutils 沙盒中开发）。
TeX（LaTeX 写入器正在沙盒中实现）。
Docutils 原生伪 XML（实现为 docutils.writers.pseudoxml，用于测试）。
纯文本
reStructuredText？

输入/输出

I/O 类提供了一个统一的 API 用于底层输入和输出。子类将存在于各种输入/输出机制中。但是，它们可以被认为是实现细节。大多数应用程序应该可以使用与发布者相关联的便利函数之一来满足。

I/O 类目前处于初步阶段；还有很多工作要做。问题

如何在 API 中表示多文件输入（文件和目录）？
如何表示多文件输出？也许是“写入器”变体，每个输出分发类型一个？或者带有关联转换的输出对象？

职责

从输入源（输入对象）读取数据或将数据写入输出目标（输出对象）。

输入源示例

磁盘上的单个文件或流（实现为docutils.io.FileInput）。
磁盘上的多个文件（MultiFileInput？）。
Python 源文件：模块和包。
从客户端应用程序接收到的 Python 字符串（实现为docutils.io.StringInput）。

输出目标示例

磁盘上的单个文件或流（实现为docutils.io.FileOutput）。
磁盘上的目录和文件树。
返回给客户端应用程序的 Python 字符串（实现为docutils.io.StringOutput）。
无输出；对于仅使用正常输出一部分的程序化应用程序很有用（实现为docutils.io.NullOutput）。
内存中单个树形数据结构。
内存中其他一些数据结构。

Docutils 包结构

包“docutils”。
- 模块“__init__.py”包含：类“Component”，Docutils 组件的基类；类“SettingsSpec”，指定运行时设置的基类（由 docutils.frontend 使用）；以及类“TransformSpec”，指定转换的基类。
- 模块“docutils.core”包含外观类“Publisher”和便利函数。请参见上文发布者。
- 模块“docutils.frontend”提供运行时设置支持，用于程序化使用和前端工具（包括配置文件支持，以及命令行参数和选项处理）。
- 模块“docutils.io”提供了一个统一的 API 用于底层输入和输出。请参见上文输入/输出。
- 模块“docutils.nodes”包含 Docutils 文档树元素类库以及树遍历访问者模式基类。请参见下文文档树。
- 模块“docutils.statemachine”包含一个有限状态机，专门用于基于正则表达式的文本过滤器和解析器。reStructuredText 解析器实现基于此模块。
- 模块“docutils.urischemes”包含已知 URI 方案（“http”、“ftp”、“mail”等）的映射。
- 模块“docutils.utils”包含实用函数和类，包括一个记录器类（“Reporter”；请参见下文错误处理）。
- 包“docutils.parsers”：标记解析器。
  - 函数“get_parser_class(parser_name)”按名称返回解析器模块。类“Parser”是特定解析器的基类。（docutils/parsers/__init__.py）
  - 包“docutils.parsers.rst”：reStructuredText 解析器。
  - 可以添加其他标记解析器。
  请参见上文解析器。
- 包“docutils.readers”：上下文感知输入读取器。
  - 函数“get_reader_class(reader_name)”按名称或别名返回读取器模块。类“Reader”是特定读取器的基类。（docutils/readers/__init__.py）
  - 模块“docutils.readers.standalone”读取独立的文档文件。
  - 模块“docutils.readers.pep”读取 PEP（Python 增强提案）。
  - 要添加的读取器：Python 源代码（结构和文档字符串）、电子邮件、FAQ，以及可能还有 Wiki 等。
  请参见上文读取器。
- 包“docutils.writers”：输出格式写入器。
  - 函数“get_writer_class(writer_name)”按名称返回写入器模块。类“Writer”是特定写入器的基类。（docutils/writers/__init__.py）
  - 模块“docutils.writers.html4css1”是一个简单的 HTML 文档树写入器，用于 HTML 4.01 和 CSS1。
  - 模块“docutils.writers.docutils_xml”以 XML 形式写入内部文档树。
  - 模块“docutils.writers.pseudoxml”是一个简单的内部文档树写入器；它写入缩进的伪 XML。
  - 要添加的写入器：HTML 3.2 或 4.01-loose、XML（各种形式，如 DocBook）、PDF、TeX、纯文本、reStructuredText，以及可能还有其他。
  请参见上文写入器。
- 包“docutils.transforms”：树转换类。
  - 类“Transformer”存储转换并将它们应用于文档树。（docutils/transforms/__init__.py）
  - 类“Transform”是特定转换的基类。（docutils/transforms/__init__.py）
  - 每个模块都包含相关的转换类。
  请参见上文转换。
- 包“docutils.languages”：语言模块包含特定于语言的字符串和映射。它们以其语言标识符命名（如下文文档字符串格式的选择中所定义），将连字符转换为下划线。
  - 函数“get_language(language_code)”返回匹配的语言模块。（docutils/languages/__init__.py）
  - 模块：en.py（英语）、de.py（德语）、fr.py（法语）、it.py（意大利语）、sk.py（斯洛伐克语）、sv.py（瑞典语）。
  - 要添加其他语言。
第三方模块：“extras”目录。仅当这些模块在 Python 安装中不存在时才会安装这些模块。
- extras/optparse.py和extras/textwrap.py提供选项解析和命令行帮助；来自 Greg Ward 的http://optik.sf.net/项目，出于方便而包含。
- extras/roman.py包含罗马数字转换例程。

前端工具

tools/目录包含几个用于常见 Docutils 处理的前端。有关详细信息，请参见Docutils 前端工具。

文档树

Docutils 在内部使用单个中间数据结构，在组件之间的接口中；它在docutils.nodes模块中定义。不需要任何组件在内部使用此数据结构，只需在组件之间使用，如上文Docutils 项目模型中的图所示。

允许自定义节点类型，前提是（a）转换在它们到达 Writer 本身之前将其转换为标准 Docutils 节点，或者（b）某些 Writer 明确支持自定义节点，并将其包装在已过滤的“挂起”节点中。条件 (a) 的一个示例是Python 源读取器（见下文），其中“样式”转换转换自定义节点。HTML<meta>标记是条件 (b) 的一个示例；它受 HTML Writer 支持，但不受其他 Writer 支持。reStructuredText 的“meta”指令创建一个“挂起”节点，其中包含嵌入的“meta”节点只能由与 HTML 兼容的写入器处理的知识。“挂起”节点由docutils.transforms.components.Filter转换解析，该转换检查调用写入器是否支持 HTML；如果它不支持，则“挂起”节点（和封闭的“meta”节点）将从文档中删除。

文档树数据结构类似于 DOM 树，但使用特定的节点名称（类）而不是 DOM 的通用节点。模式在 XML DTD（可扩展标记语言文档类型定义）中记录，它分为两部分

Docutils 通用 DTD，docutils.dtd，以及
OASIS 交换表模型，soextbl.dtd。

DTD 定义了一组丰富的元素，适用于许多输入和输出格式。DTD 保留了重建原始输入文本或其合理摹本所需的所有信息。

有关详细信息（不完整），请参见Docutils 文档树。

错误处理

当解析器遇到标记错误时，它会插入系统消息（DTD 元素“system_message”）。系统消息有五个级别

级别 0，“DEBUG”：内部报告问题。对处理没有影响。级别 0 系统消息与其他消息分开处理。
级别 1，“INFO”：可以忽略的次要问题。对处理的影响很小或没有影响。通常不报告级别 1 系统消息。
级别 2，“WARNING”：应该解决的问题。如果忽略，输出可能会出现小问题。通常会报告级别 2 系统消息，但不会停止处理
级别 3，“ERROR”：应该解决的主要问题。如果忽略，输出将包含不可预测的错误。通常会报告级别 3 系统消息，但不会停止处理
级别 4，“SEVERE”：必须解决的严重错误。通常将级别 4 系统消息转换为异常，从而停止处理。如果忽略，输出将包含严重错误。

尽管最初的消息级别是独立设计的，但它们与VMS 错误条件严重性级别具有很强的对应关系；级别 1 到 4 的引号中的名称借自 VMS。错误处理此后受到log4j 项目的影响。

Python 源码读取器

Python 源读取器（“PySource”）是读取 Python 源文件、在上下文中提取文档字符串，然后解析、链接和将文档字符串组合成一个连贯的整体的 Docutils 组件。它是一个主要且非平凡的组件，目前正在 Docutils 沙箱中进行实验性开发。此处介绍高级设计问题。

处理模型

此模型将随着时间的推移而发展，并结合经验和发现。

PySource 读取器使用 Input 类将 Python 包和模块读入字符串树。
Python 模块被解析，将字符串树转换为带有文档字符串节点的抽象语法树树。
抽象语法树被转换为包/模块的内部表示。提取文档字符串以及代码结构详细信息。请参见下文AST 挖掘。为步骤 6 中的查找构建命名空间。
一次一个，文档字符串被解析，生成标准的 Docutils doctree。
PySource 将所有单个文档字符串的 doctree 组合成一个与包/模块/类结构平行的 Python 特定自定义 Docutils 树；这是一种自定义的读取器特定内部表示（请参见Docutils Python 源 DTD）。必须合并命名空间：Python 标识符、超链接目标。
文档字符串（解释性文本）到 Python 标识符的交叉引用根据 Python 命名空间查找规则解析。请参阅下面标识符交叉引用。
一个“样式”转换应用于自定义 doctree（由转换器应用），自定义节点使用标准节点作为基本元素进行渲染，并输出一个标准的文档树。请参阅下面样式转换。
其他转换由转换器应用于标准 doctree。
标准 doctree 被发送到一个 Writer，它将文档转换为具体的格式（HTML、PDF 等）。
Writer 使用 Output 类将生成的数据写入其目标位置（磁盘文件、目录和文件等）。

AST 挖掘

将编写（或改编）抽象语法树挖掘代码，该代码扫描解析的 Python 模块，并返回一个有序树，其中包含以下所有对象的名称、文档字符串（包括属性和附加文档字符串；见下文）以及其他信息（括号内）：

包
模块
模块属性（+ 初始值）
类（+ 继承）
类属性（+ 初始值）
实例属性（+ 初始值）
方法（+ 参数 & 默认值）
函数（+ 参数 & 默认值）

（也提取注释吗？例如，模块开头的注释是书目字段列表的理想位置。）

为了评估解释性文本交叉引用，还需要上述每个对象的命名空间。

请参阅 python-dev/docstring-develop 线程“AST 挖掘”，该线程于 2001 年 8 月 14 日启动。

文档字符串提取规则

检查内容
1. 如果正在记录的模块中存在“__all__”变量，则仅检查“__all__”中列出的标识符的文档字符串。
2. 在没有“__all__”的情况下，将检查所有标识符，但名称为私有的标识符除外（名称以“_”开头，但不以“__”开头和结尾）。
3. 1a 和 1b 可以被运行时设置覆盖。
位置
文档字符串是字符串字面量表达式，在 Python 模块中的以下位置被识别：
1. 在模块、函数定义、类定义或方法定义的开头，在任何注释之后。这是 Python __doc__ 属性的标准。
2. 在模块、类定义或 __init__ 方法定义的顶层，紧跟在简单的赋值语句之后，在任何注释之后。请参阅下面属性文档字符串。
3. 在 (a) 和 (b) 中的文档字符串之后立即找到的其他字符串字面量将被识别、提取并连接。请参阅下面附加文档字符串。
4. @@@ 2.2 风格的“属性”与属性文档字符串？等待语法？
方法
尽可能地，Docutils 应该解析 Python 模块，而不是导入它们。这有几个原因：
- 导入不受信任的代码本质上是不安全的。
- 使用内省检查导入的模块时，源信息会丢失，例如注释和定义的顺序。
- 文档字符串应该在字节码编译器忽略字符串字面量表达式的位置（上面 2b 和 2c）被识别，这意味着导入模块将丢失这些文档字符串。
当然，应该使用标准的 Python 解析工具，例如“parser”库模块。

当模块的 Python 源代码不可用（即仅存在 .pyc 文件）或对于 C 扩展模块时，要访问文档字符串，只能导入该模块，并且必须接受任何限制。

由于属性文档字符串和附加文档字符串被 Python 字节码编译器忽略，因此使用它们不会导致命名空间污染或运行时膨胀。它们不会分配给 __doc__ 或任何其他属性。模块的初始解析可能会导致轻微的性能下降。

属性文档字符串

（这是PEP 224的简化版本。）

紧跟在赋值语句后面的字符串字面量被文档字符串提取机制解释为赋值语句目标的文档字符串，在以下条件下：

赋值必须在以下上下文之一中：
1. 在模块的顶层（即，不嵌套在复合语句（如循环或条件语句）中）：模块属性。
2. 在类定义的顶层：类属性。
3. 在类的“__init__”方法定义的顶层：实例属性。在其他方法中分配的实例属性被认为是实现细节。（@@@ __new__ 方法？）
4. 在模块或类定义的顶层进行函数属性赋值。
由于上述每个上下文都在顶层（即，在定义的最外层套件中），因此可能需要为有条件地或在循环中分配的属性放置虚拟赋值。
赋值必须指向单个目标，而不是指向目标列表或元组。
目标的形式
1. 对于上面 1a 和 1b 中的上下文，目标必须是简单的标识符（而不是带点的标识符、带下标的表达式或带切片的表达式）。
2. 对于上面 1c 中的上下文，目标必须采用“self.attrib”的形式，其中“self”与“__init__”方法的第一个参数（实例参数）匹配，而“attrib”是与 3a 中相同的简单标识符。
3. 对于上面 1d 中的上下文，目标必须采用“name.attrib”的形式，其中“name”与已定义的函数或方法名称匹配，而“attrib”是与 3a 中相同的简单标识符。

可以在属性文档字符串之后使用空行来强调赋值和文档字符串之间的联系。

示例

g = 'module attribute (module-global variable)'
"""This is g's docstring."""

class AClass:

    c = 'class attribute'
    """This is AClass.c's docstring."""

    def __init__(self):
        """Method __init__'s docstring."""

        self.i = 'instance attribute'
        """This is self.i's docstring."""

def f(x):
    """Function f's docstring."""
    return x**2

f.a = 1
"""Function attribute f.a's docstring."""

额外文档字符串

（这个想法改编自PEP 216。）

许多程序员希望广泛使用文档字符串进行 API 文档。但是，文档字符串确实占用运行程序中的空间，因此一些程序员不愿意“膨胀”他们的代码。此外，并非所有 API 文档都适用于交互式环境，在这些环境中会显示 __doc__。

Docutils 的文档字符串提取工具将连接出现在定义开头或简单赋值之后的全部字符串字面量表达式。仅定义中的第一个字符串可用作 __doc__，并且可用于适合交互式会话的简短用法文本；后续字符串字面量和所有属性文档字符串都被 Python 字节码编译器忽略，并且可能包含更广泛的 API 信息。

示例

def function(arg):
    """This is __doc__, function's docstring."""
    """
    This is an additional docstring, ignored by the byte-code
    compiler, but extracted by Docutils.
    """
    pass

文档字符串格式选择

与其强迫每个人都使用单一的文档字符串格式，不如通过处理系统允许多种输入格式。一个特殊的变量 __docformat__ 可以在模块的顶层，在任何函数或类定义之前出现。随着时间的推移或通过法令，应该出现标准格式或一组格式。

模块的 __docformat__ 变量仅适用于在模块文件中定义的对象。特别是，包的 __init__.py 文件中的 __docformat__ 变量不适用于子包和子模块中定义的对象。

__docformat__ 变量是一个字符串，包含正在使用的格式的名称，一个不区分大小写的字符串，与输入解析器的模块或包名称匹配（即，与“导入”模块或包所需的名称相同），或一个注册的别名。如果未指定 __docformat__，则默认格式目前为“纯文本”；如果将来建立标准格式，这可能会更改为标准格式。

__docformat__ 字符串可以包含一个可选的第二个字段，该字段由一个空格与格式名称（第一个字段）分隔：一个不区分大小写的语言标识符，如RFC 1766中定义。典型的语言标识符由来自ISO 639的 2 个字母的语言代码组成（仅当不存在 2 个字母的代码时才使用 3 个字母的代码；RFC 1766目前正在修订以允许 3 个字母的代码）。如果未指定语言标识符，则默认为英语的“en”。语言标识符传递给解析器，可用于依赖语言的标记功能。

标识符交叉引用

在 Python 文档字符串中，解释性文本用于对程序标识符进行分类和标记，例如变量、函数、类和模块的名称。如果只给出标识符，则根据 Python 命名空间查找规则隐式推断其作用。对于函数和方法（即使是动态分配的），也可以包含括号（'()'）

This function uses `another()` to do its work.

对于类、实例和模块属性，在必要时使用带点的标识符。例如（使用 reStructuredText 标记）：

class Keeper(Storer):

    """
    Extend `Storer`.  Class attribute `instances` keeps track
    of the number of `Keeper` objects instantiated.
    """

    instances = 0
    """How many `Keeper` objects are there?"""

    def __init__(self):
        """
        Extend `Storer.__init__()` to keep track of instances.

        Keep count in `Keeper.instances`, data in `self.data`.
        """
        Storer.__init__(self)
        Keeper.instances += 1

        self.data = []
        """Store data in a list, most recent last."""

    def store_data(self, data):
        """
        Extend `Storer.store_data()`; append new `data` to a
        list (in `self.data`).
        """
        self.data = data

每个用反引号 (“`”) 括起来的标识符都将成为对其自身定义的引用。

样式转换

样式转换是特定于 PySource 阅读器的专用转换。PySource 阅读器不必对样式做出任何决定；它只需生成一个逻辑构建的文档树，进行解析和链接，包括自定义节点类型。样式转换了解阅读器创建的自定义节点，并将它们转换为标准的 Docutils 节点。

可以实现多个Stylist转换，并在运行时（通过“–style”或“–stylist”命令行选项）选择其中一个。每个Stylist转换都实现了一种不同的布局或样式；因此得名。它们将Reader的上下文理解部分与处理的布局生成部分解耦，从而产生一个更灵活、更强大的系统。这也用于“将样式与内容分离”，这是SGML/XML的理想目标。

通过保持执行样式设置的代码段小巧且模块化，人们更容易创建自己的样式。现有工具的“入门门槛”过高；提取Stylist代码将大大降低门槛。

上次修改时间：2023-09-09 17:39:29 GMT

Python 增强提案