拒绝通知

这项提议似乎已经后继乏力。

摘要

Python 自身就适合内联文档。凭借其内置的文档字符串语法，Python 中可以轻松实现有限形式的文学编程。然而，目前还没有令人满意的标准工具来提取和处理 Python 文档字符串。标准工具集的缺乏是 Python 基础设施中的一个显著空白；本 PEP 旨在填补这一空白。

围绕文档字符串处理的问题一直存在争议且难以解决。本 PEP 提出了一个通用的文档字符串处理系统 (DPS) 框架，该框架将组件（程序和概念）分离出来，从而可以通过共识（一种解决方案）或通过分歧（多种解决方案）来解决个别问题。它提倡标准接口，允许使用各种插件组件（输入上下文读取器、标记解析器和输出格式写入器）。

DPS 框架的概念独立于实现细节而呈现。

文档字符串 PEPs 路线图

文档字符串处理有许多方面。“文档字符串 PEPs”已将问题分解开来，以便单独处理每个问题，或尽可能接近单独处理。各个方面和相关的 PEPs 如下：

• 文档字符串语法。PEP 287，“reStructuredText 文档字符串格式”，提出了 Python 文档字符串、PEPs 和其他用途的语法。
• 文档字符串语义至少包含两个方面：
  • 约定：文档字符串的高级结构。在PEP 257，“文档字符串约定”中处理。
  • 方法论：文档字符串信息内容的规则。尚未解决。
• 处理机制。本 PEP（PEP 256）概述了抽象文档字符串处理系统 (DPS) 的高级问题和规范。PEP 258，“Docutils 设计规范”，是正在开发的一个 DPS 的设计和实现概述。
• 输出样式：开发人员希望从其源代码生成的文档美观，而对于这意味着什么，有许多不同的想法。PEP 258 提到了“样式转换”。文档字符串处理的这一方面尚未得到充分探索。

通过将问题分离出来，我们可以更容易地达成共识（更小的争论 ;-），并更乐意接受分歧。

基本原理

其他一些语言也有标准的内联文档系统。例如，Perl 有 POD (“Plain Old Documentation”)，Java 有 Javadoc，但两者都与 Python 的方式不兼容。POD 语法非常明确，但在可读性方面追随 Perl。Javadoc 以 HTML 为中心；除了“@field”标签外，原始 HTML 用于标记。还有一些通用工具，例如 Autoduck 和 Web (Tangle & Weave)，适用于多种语言。

为 Python 编写自动文档系统进行了许多尝试（非详尽列表）：

• Marc-Andre Lemburg 的 doc.py
• Daniel Larsson 的 pythondoc & gendoc
• Doug Hellmann 的 HappyDoc
• Laurence Tratt 的 Crystal（网络上已不可用）
• Ka-Ping Yee 的 pydoc (pydoc.py 现已成为 Python 标准库的一部分；见下文)
• Tony Ibbs 的 docutils (Tony 已将此名称捐赠给 Docutils 项目)
• Edward Loper 的 STminus 形式化及相关工作

这些系统，各自目标不同，取得了不同程度的成功。上述许多系统存在的问题是过度雄心与缺乏灵活性相结合。它们提供了一套自包含的组件：一个文档字符串提取系统、一个标记解析器、一个内部处理系统和一个或多个具有固定样式的输出格式编写器。不可避免地，每个系统的一个或多个方面都存在严重缺陷，并且它们不容易扩展或修改，从而无法被采纳为标准工具。

（至少对本文作者而言）“全有或全无”的方法无法成功已变得清晰，因为没有任何一个 monolithic 的自包含系统可能得到所有相关方的同意。为扩展而设计的模块化组件方法，其中组件可以多重实现，可能是成功的唯一机会。标准的组件间 API 将使 DPS 组件易于理解，而无需详细了解整个系统，从而降低贡献的门槛，并最终形成一个丰富多样的系统。

文档字符串处理系统的每个组件都应独立开发。“最佳品种”系统应被选中，可以从现有系统合并，和/或重新开发。该系统应包含在 Python 的标准库中。

规范

文档字符串处理系统框架分解如下：

1. 文档字符串约定。记录了诸如以下问题：
   • 应在何处记录什么。
   • 第一行是单行摘要。

   PEP 257 记录了其中一些问题。

2. 文档字符串处理系统设计规范。记录了诸如以下问题：
   • 高级规范：DPS 的作用。
   • 可执行脚本的命令行接口。
   • 系统 Python API。
   • 文档字符串提取规则。
   • 封装输入上下文的读取器。
   • 解析器。
   • 文档树：中间内部数据结构。解析器和读取器的输出，以及写入器的输入都共享相同的数据结构。
   • 修改文档树的转换。
   • 输出格式的写入器。
   • 分发器，处理输出管理（一个文件、多个文件或内存中的对象）。

   这些问题适用于任何文档字符串处理系统的实现。PEP 258 记录了这些问题。

3. 文档字符串处理系统实现。
4. 输入标记规范：文档字符串语法。PEP 287 提出了标准语法。
5. 输入解析器实现。
6. 输入上下文读取器（“模式”：Python 源代码、PEP、独立文本文件、电子邮件等）和实现。
7. 样式器：某些输入上下文读取器可能具有关联的样式器，允许各种输出文档样式。
8. 输出格式（HTML、XML、TeX、DocBook、info 等）和写入器实现。

组件 1、2/3/5 和 4 是单独的配套 PEP 的主题。如果框架或语法/解析器有其他实现，则可能需要额外的 PEP。组件 6 和 7 的每个组件都将需要多个实现；PEP 机制可能对这些组件来说是多余的。

项目网站

已为这项工作在 http://docutils.sourceforge.net/ 建立了一个 SourceForge 项目。

版权

本文档已置于公共领域。

致谢

本文借鉴了 Python Doc-SIG 档案中的思想。感谢所有过去和现在的成员。