Twisted 编写规范

Twisted 编写规范描述了我们在叙述性文档中偏好的文档编写风格。

此规范特别适用于操作指南和其他描述性文档。有关编写 API 文档，请参阅 我们编码规范中的 Docstrings 部分。

本文档旨在帮助 Twisted 文档作者制作不包含以下问题的文档

  • 误导用户关于什么是好的 Twisted 风格；

  • 误导用户认为高级操作指南是编写第一个 Twisted 服务器的入门指南；以及

  • 误导用户关于他们是否符合文档的目标受众：例如，他们是否能够在不知道如何编写 SQL 查询的情况下使用企业。

通用风格

文档应力求清晰简洁，让 API 文档和示例代码尽可能多地讲述故事。演示和必要时支持的论据应始终优先于简单的陈述（“以下是如何使用 Deferreds 简化此代码”而不是“Deferreds 使代码更简单”）。

文档应清楚地划分为部分和子部分。这些部分，就像整个文档一样，应该有一个明确的目的。这最容易通过尝试使用有意义的标题来测试：标题为“更多细节”或“高级内容”的部分不够有目的性。应该有相当明显的方法来拆分文档。两种最常见的方法是基于任务的划分和遵循模块和类分离的划分。

文档必须使用美式英语拼写，并尽可能避免任何词汇或语法的本地变体。理想情况下应避免语法复杂的句子：这些句子会使阅读变得不必要地困难，特别是对于非母语人士而言。

在提到假设的人时（例如，“使用 twisted.web 编写的网站的用户”），应使用中性代词（他们/他们的/他们）。

对于由 Sphinx 文档生成器处理的 reStructuredText 文档，请使行短，并在自然的地方换行，例如在逗号和分号之后，而不是在第 79 列之后。我们称之为语义换行。此规则不适用于 docstrings。

Sometimes when editing a narrative documentation file, I wrap the lines semantically.
Instead of inserting a newline at 79 columns (or whatever),
or making paragraphs one long line,
I put in newlines at a point that seems logical to me.
Modern code-oriented text editors are very good at wrapping and arranging long lines.

宣传和使用文档

Twisted 文档应在“宣传”文档和“使用”文档之间保持合理的区分。“宣传”文档将 Twisted 设计或 Twisted 最佳实践与其他方法进行比较，并为 Twisted 方法进行辩护，而“使用”文档则详细描述 Twisted 方法，而无需与其他可能的方法进行比较。

虽然这两种文档都有用，但它们面向不同的受众。第一类文档，即宣传文档，对于正在研究和比较方法并试图了解 Twisted 方法或 Twisted 功能以决定它是否对他们有用的人来说很有用。第二类文档，即使用文档，对于已经决定使用 Twisted 并只是想要更多关于可用功能和架构的信息以完成其目标的人来说很有用。

由于它们面向不同的受众，因此宣传和详细的使用文档应放在不同的文件中。在“进一步阅读”或类似部分中应有它们之间的链接。

功能描述

对 Twisted 核心 2.0 版之后添加的任何功能的描述都必须在每篇文档中首次提及时包含一个说明它们是在哪个 Twisted 项目的哪个版本中添加的注释。如果它们尚未发布，请为它们提供下一个次要版本的编号。

例如，重大更改可能在引言中添加版本号

本文档描述了用于部署 Twisted 应用程序的应用程序基础设施（在 Twisted 1.3 中添加）。

除了在后续版本中添加的特定功能之外，版本不需要在文档的其他地方提及，这些功能可能应该单独提及。

创建 .tac 文件的最简单方法是 SuperTac （在 Twisted Core 99.7 中添加）…

在功能的使用方式发生重大变化的情况下，编号应为当前使用方式可用的版本的编号。例如

本文档描述了用于部署 Twisted 应用程序的应用程序基础设施（在 Twisted 2.7 中更新/大幅更新）。

链接

任何模块、类或函数名称的首次出现应始终链接到 API 文档。后续提及是否链接由作者自行决定：与特定 API 密切相关的讨论可能应该在给定部分的首次提及中链接。

鼓励操作指南之间的链接。概述文档和教程应始终链接到参考文档和深入文档。这些文档应在需要的地方相互链接：如果你想重新描述另一个模块的功能，你当然应该链接。

在引用标准库对象时，也鼓励链接到标准库文档。Twisted 文档支持 Intersphinx，并使用前缀链接到 Python 2 标准库文档（通过 py2）或 Python 3（通过 py3），具体取决于需要。

简介

Twisted 操作指南的介绍部分应紧随顶级标题，并在任何子标题之前。

Twisted 操作指南的介绍中应包含以下内容：引言和目标受众描述。

引言

文档的引言应概述文档的设计目的。它应该同时使用 Twisted 技术的正确名称和对技术的简单非 Twisted 描述。例如，在本段中，同时使用了技术的名称（“Conch”）和描述（“SSH 服务器”）

本文档描述了如何使用 Twisted SSH 实现 Conch 设置 SSH 服务器以从文件系统提供数据。

引言应相对简短，但应该像上面一样，在某个地方定义文档的目标：读者使用文档中的说明应该能够做什么。

目标受众描述

引言中的后续段落应描述文档的目标受众：谁会想要阅读它，以及他们在期望使用你的文档之前应该了解什么。例如

本文档的目标受众是 Twisted 用户，他们有一组文件系统类数据对象，他们希望通过 SFTP 将这些对象提供给经过身份验证的用户。

按照本文档中的说明操作需要你熟悉通过 Twisted Cred 系统进行身份验证的管理。

请谨慎考虑列出假设知识的程度。非常入门的文档，这些文档将成为读者第一次接触 Twisted，甚至需要指定它们依赖于 Python 和某些网络概念（端口、服务器、客户端、连接）的知识，但那些将由现有 Twisted 用户为了特定目的而寻找的文档只需要指定其他假设的 Twisted 知识。

任何不被视为“核心 Python”和/或“简单网络”的技术知识都需要明确说明，无论它们对熟悉该技术的人来说多么明显。例如，需要说明使用企业的人应该了解 SQL，并且应该知道如何设置和填充数据库以进行测试。

在可能的情况下，链接到其他文档，这些文档将为读者填补缺失的知识。优先链接到 Twisted 存储库中的文档，但这不是必需的。

文档目标

引言应以用户期望看到文档完成的任务列表结束。这些任务应该是具体的而不是抽象的，因此，与其告诉用户他们将“了解 Twisted Conch”，不如列出他们将看到文档完成的具体任务。例如

本文档将使用 Twisted Conch 演示以下任务

  • 使用文件系统后端创建匿名访问只读 SFTP 服务器；

  • 使用连接到 HTTP 服务器的代理后端创建匿名访问只读 SFTP 服务器；以及

  • 使用文件系统后端创建匿名访问读写 SFTP 服务器。

在许多情况下，这实际上将是你的代码示例的列表，但它不一定是。如果你的代码的大部分内容都用于设计讨论，你的目标可能类似于以下内容

本文档将讨论编写 Conch 服务器的以下设计方面

  • 用户身份验证；以及

  • 数据后端的选择。

示例代码

在可能的情况下，应提供示例代码来说明某种技术或功能。

示例代码应尽可能满足以下要求

  • 示例代码应是一个完整的可运行示例，适合读者复制、粘贴和运行（在可能的情况下，提供指向要下载的文件的链接）；

  • 示例代码应简短；

  • 示例代码应进行非常广泛的注释，假设此代码可能被 Twisted 新手阅读；

  • 示例代码应符合 编码规范；以及

  • 示例代码应体现“最佳实践”，不仅针对目标功能，还包括对应用程序框架的使用等。

完整的可运行示例的要求有时会强迫作者编写一些虚拟函数：在 Twisted 文档中，最常见的例子是需要一个函数来生成一个 Deferred 并经过一段时间后触发它。例如，可以使用 deferLater 在一段时间后触发回调：

from twisted.internet import task, reactor

def getDummyDeferred():
    """
    Dummy method which returns a deferred that will fire in 5 seconds with
    a result
    """
    return task.deferLater(reactor, 5, lambda x: "RESULT")

如上例所示，必须以尽可能多的方式清楚地标记该函数是一个虚拟函数：在函数名中使用 Dummy，在文档字符串中解释它是虚拟函数，并标记特定行是为了演示目的而创建的效果。在大多数情况下，这将使读者不会将此虚拟方法误认为是他们在 Twisted 代码中应该使用的习惯用法。

结论

howto 的结论应紧随文件中最后一个章节标题。此标题通常称为“结论”。

howto 的结论应提醒读者他们在阅读文档时完成的任务。例如

在本文件中，您已经了解了如何

  1. 设置匿名只读 SFTP 服务器；

  2. 设置用户需要身份验证的 SFTP 服务器；

  3. 设置用户根据身份验证限制在文件系统某些部分的 SFTP 服务器；以及

  4. 设置用户根据身份验证对文件系统某些部分具有写访问权限的 SFTP 服务器。

如果合适，howto 可以用指向其他文档的链接来补充此描述，这些文档可能对读者及其新获得的知识感兴趣。但是，这些链接应限于对至少一项列出任务的相当明显的扩展。