拒绝通知

该提案似乎已失去动力。

摘要

Python 非常适合内联文档。使用其内置的文档字符串语法，在 Python 中很容易实现有限形式的 文学编程。但是，目前没有令人满意的标准工具可以提取和处理 Python 文档字符串。缺乏标准工具集是 Python 基础设施中的一个重大差距；本 PEP 旨在填补这一差距。

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

DPS 框架的概念与实现细节无关。

文档字符串 PEP 路线图

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

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

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

基本原理

其他一些语言的标准内联文档系统。例如，Perl 有 POD（“普通旧文档”）和 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 正式化和相关工作

这些系统，每个都有不同的目标，取得了不同程度的成功。上述许多系统的一个问题是野心太大，但灵活性不足。它们提供了一套独立的组件：文档字符串提取系统、标记解析器、内部处理系统以及一个或多个具有固定样式的输出格式编写器。不可避免地，每个系统的某些方面都会有严重的缺陷，并且它们不容易扩展或修改，从而无法将它们作为标准工具采用。

越来越明显（至少对于本文作者而言），“全有或全无”的方法不会成功，因为不可能由所有利益相关者就任何单一的自包含系统达成一致。一种面向扩展的模块化组件方法，其中组件可以被多次实现，可能是唯一的机会。标准的组件间 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 机制对于这些组件来说可能有点过头。

项目网站

一个 SourceForge 项目已在 http://docutils.sourceforge.net/ 为此工作而设立。

版权

本文件已进入公有领域。

鸣谢

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