PEP 12 – reStructuredText PEP 模板示例
- 作者:
- David Goodger <goodger at python.org>, Barry Warsaw <barry at python.org>, Brett Cannon <brett at python.org>
- 状态:
- 活跃
- 类型:
- 流程
- 创建日期:
- 2002年8月5日
- 发布历史:
- 2002年8月30日
摘要
本 PEP 提供了一个用于创建您自己的 reStructuredText PEP 的样板或示例模板。结合 PEP 1 中的内容指南，这将使您能够轻松地使自己的 PEP 符合以下概述的格式。
注意：如果您正在通过网络阅读本 PEP，您应该首先获取本 PEP 的文本（reStructuredText）源代码，以完成以下步骤。请勿将 HTML 文件用作您的模板！
本（或任何）PEP 的源代码可以在PEPs 仓库中找到，也可以通过每个 PEP 底部的链接找到。
基本原理
如果您打算提交 PEP，您必须使用此模板，并结合以下格式指南，以确保您的 PEP 提交不会因格式问题而被自动拒绝。
reStructuredText 为 PEP 作者提供了有用的功能和表达能力，同时保持了源代码的易读性。处理后的 HTML 形式使功能对读者来说易于访问：实时超链接、样式文本、表格、图像和自动目录等优点。
如何使用此模板
要使用此模板，您必须首先决定您的 PEP 是信息性 PEP 还是标准追踪 PEP。大多数 PEP 是标准追踪 PEP，因为它们为 Python 语言或标准库提出了新功能。如有疑问，请阅读PEP 1 获取详细信息，或在 PEP 仓库上提出跟踪器问题以寻求帮助。
一旦您决定了您的 PEP 类型，请按照以下说明进行操作。
- 复制此文件（
.rst文件，而不是 HTML！）并执行以下编辑。将新文件命名为pep-NNNN.rst，使用下一个可用编号（未被已发布或在 PR 中的 PEP 使用）。 - 将“PEP: 12”标题替换为“PEP: NNNN”，与文件名匹配。请注意，文件名应填充零（例如
pep-0012.rst），但标题不应填充（PEP: 12）。 - 将“Title”标题更改为您的 PEP 的标题。
- 更改“Author”标题以包含您的姓名，以及可选的电子邮件地址。请务必仔细遵循格式：您的姓名必须首先出现，并且不能包含在括号中。您的电子邮件地址可以出现在第二位（或可以省略），如果出现，它必须出现在尖括号中。混淆您的电子邮件地址是可以的。
- 如果没有作者是 Python 核心开发者，请添加“Sponsor”标题，其中包含赞助您的 PEP 的核心开发者的姓名。
- 在“Discussions-To”标题下添加 PEP 规范讨论串的直接 URL（例如 Python-Dev、Discourse 等）。如果讨论串将在 PEP 作为官方草案提交后创建，则最初只放置“Pending”是可以的，但请记住在 PEP 成功合并到 PEP 仓库并创建相应的讨论串后尽快用 URL 更新 PEP。有关更多详细信息，请参阅PEP 1。
- 将“Status”标题更改为“Draft”。
- 对于标准追踪 PEP，将“Type”标题更改为“Standards Track”。
- 对于信息性 PEP，将“Type”标题更改为“Informational”。
- 对于标准追踪 PEP，如果您的功能依赖于其他正在开发的 PEP 的接受，请在“Type”标题后面添加“Requires”标题。该值应为您所依赖的 PEP 的 PEP 编号。如果您的依赖功能在最终 PEP 中描述，请勿添加此标题。
- 将“Created”标题更改为今天的日期。请务必仔细遵循格式：它必须采用
dd-mmm-yyyy格式，其中mmm是3个英文字母的月份缩写，即 Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec 之一。 - 对于标准追踪 PEP，在“Created”标题之后，添加“Python-Version”标题并将值设置为 Python 的下一个计划版本，即您的新功能有望首次出现的版本。此处不要使用 alpha 或 beta 版本代号。因此，如果 Python 的最新版本是 2.2 alpha 1，并且您希望将新功能纳入 Python 2.2，请将标题设置为
Python-Version: 2.2
- 如果 PEP 属于主题索引中显示的主题之一，请添加“Topic”标题。大多数 PEP 不属于。
- 暂时不要动“Post-History”；每次将您的 PEP 发布到指定的讨论论坛（并如上所述用该链接更新“Discussions-To”标题）时，您都会向此标题添加日期和相应的链接。对于每个讨论串，使用日期（
dd-mmm-yyy格式）作为链接文本，并以内联匿名 reST 超链接的形式插入 URL，每个帖子之间用逗号分隔。如果您在 2001 年 8 月 14 日和 2001 年 9 月 3 日发布了您的 PEP 的讨论串，则“Post-History”标题将如下所示，例如
Post-History: `14-Aug-2001 <https://www.example.com/thread_1>`__, `03-Sept-2001 <https://www.example.com/thread_2>`__
一旦您发布了新的讨论串，您就应该在此处添加新的日期/链接。
- 如果您的 PEP 取代了早期的 PEP，请添加“Replaces”标题。此标题的值是您的新 PEP 正在替换的 PEP 的编号。仅当旧的 PEP 处于“最终”形式时才添加此标题，即已接受、最终或已拒绝。如果您正在提交一个竞争性想法，则不会替换较旧的开放 PEP。
- 现在编写您的摘要、基本原理和 PEP 的其他内容，用您自己的文本替换所有这些废话。请务必遵守以下格式指南，特别是禁止制表符和缩进要求。请参阅下面的“建议的章节”以获取要包含的章节模板。
- 更新您的脚注部分，列出文本中引用的所有脚注和非内联链接目标。
- 运行
./build.py以确保 PEP 渲染无误，并检查build/pep-NNNN.html中的输出是否符合您的预期。 - 创建针对PEPs 仓库的拉取请求。
作为参考，这里列出了所有可能的标题字段（所有括号中的内容都应替换，或者如果字段带有 leading * 标记为可选且不适用于您的 PEP，则应将其删除）
PEP: [NNN]
Title: [...]
Author: [Full Name <email at example.com>]
Sponsor: *[Full Name <email at example.com>]
PEP-Delegate:
Discussions-To: [URL]
Status: Draft
Type: [Standards Track | Informational | Process]
Topic: *[Governance | Packaging | Release | Typing]
Requires: *[NNN]
Created: [DD-MMM-YYYY]
Python-Version: *[M.N]
Post-History: [`DD-MMM-YYYY <URL>`__]
Replaces: *[NNN]
Superseded-By: *[NNN]
Resolution:
reStructuredText PEP 格式要求
以下是 reStructuredText 语法的 PEP 特定摘要。为简洁起见，省略了许多细节。有关更多详细信息，请参阅下面的资源。字面块（不进行标记处理）用于整个示例，以说明纯文本标记。
通用
行通常不应超出第 79 列，URL 和类似情况除外。文档中绝不能出现制表符。
章节标题
PEP 标题必须从第零列开始，每个单词的首字母必须像书名一样大写。首字母缩略词应全部大写。章节标题必须用下划线装饰，这是一个重复的标点符号，从第零列开始，并且必须至少延伸到标题文本的右边缘（至少 4 个字符）。第一级章节标题用“=”（等号）下划线，第二级章节标题用“-”（连字符）下划线，第三级章节标题用“'”（单引号或撇号）下划线。例如
First-Level Title
=================
Second-Level Title
------------------
Third-Level Title
'''''''''''''''''
如果您的 PEP 中有超过三级章节，您可以为第一级和第二级插入带有上划线/下划线装饰的标题，如下所示
============================
First-Level Title (optional)
============================
-----------------------------
Second-Level Title (optional)
-----------------------------
Third-Level Title
=================
Fourth-Level Title
------------------
Fifth-Level Title
'''''''''''''''''
您的 PEP 不应有超过五级章节。如果确实有，您应该考虑重写它。
章节正文的最后一行与下一个章节标题之间必须有两个空行。如果小节标题紧跟在章节标题之后，一个空行就足够了。
每个章节的正文通常不缩进，尽管某些结构确实使用缩进，如下所述。空行用于分隔结构。
段落
段落是左对齐的文本块，由空行分隔。段落不缩进，除非它们是缩进结构（如块引用或列表项）的一部分。
内联标记
段落和其他文本块中的部分文本可以设置样式。例如
Text may be marked as *emphasized* (single asterisk markup,
typically shown in italics) or **strongly emphasized** (double
asterisks, typically boldface). ``Inline literals`` (using double
backquotes) are typically rendered in a monospaced typeface. No
further markup recognition is done within the double backquotes,
so they're safe for any kind of code snippets.
块引用
块引用由缩进的正文元素组成。例如
This is a paragraph.
This is a block quote.
A block quote may contain many paragraphs.
块引用用于引用其他来源的扩展段落。块引用可以嵌套在其他正文元素中。每级缩进使用 4 个空格。
字面块
字面块用于代码示例和其他预格式化文本。要指示字面块，请在缩进的文本块前加上“::”（两个冒号），或使用.. code-block::指令。将文本块缩进 4 个空格；字面块将持续到缩进结束。例如
This is a typical paragraph. A literal block follows.
::
for a in [5, 4, 3, 2, 1]: # this is program code, shown as-is
print(a)
print("it's...")
“::”在任何段落末尾也会被识别；如果前面没有紧跟空白字符，一个冒号将在最终输出中可见
This is an example::
Literal block
默认情况下，字面块将以 Python 代码进行语法高亮显示。对于包含其他语言/格式代码或数据的特定块，请使用.. code-block:: language指令，将适当的 Pygments 词法分析器 的“短名称”（或text以禁用高亮显示）替换language。例如
.. code-block:: rst
An example of the ``rst`` lexer (i.e. *reStructuredText*).
对于主要包含特定语言的字面块的 PEP，请在 PEP 正文顶部（标题下方和摘要上方）使用带有适当language的.. highlight:: language指令。所有字面块都将被视为该语言，除非在特定的.. code-block中另有说明。例如
.. highlight:: c
Abstract
========
Here's some C code::
printf("Hello, World!\n");
列表
项目符号列表项以“-”、“*”或“+”（连字符、星号或加号）之一开头，后跟空格和列表项正文。列表项正文必须左对齐并相对于项目符号缩进；项目符号后的文本立即决定缩进。例如
This paragraph is followed by a list.
* This is the first bullet list item. The blank line above the
first list item is required; blank lines between list items
(such as below this paragraph) are optional.
* This is the first paragraph in the second item in the list.
This is the second paragraph in the second item in the list.
The blank line above this paragraph is required. The left edge
of this paragraph lines up with the paragraph above, both
indented relative to the bullet.
- This is a sublist. The bullet lines up with the left edge of
the text blocks above. A sublist is a new list so requires a
blank line above and below.
* This is the third item of the main list.
This paragraph is not part of the list.
编号列表项类似，但使用编号而不是项目符号。编号是数字（1, 2, 3, ...）、字母（A, B, C, ...；大写或小写）或罗马数字（i, ii, iii, iv, ...；大写或小写），格式为句点后缀（“1.”、“2.”）、括号（“(1)”、“(2)”）或右括号后缀（“1)”、“2)”）。例如
1. As with bullet list items, the left edge of paragraphs must
align.
2. Each list item may contain multiple paragraphs, sublists, etc.
This is the second paragraph of the second list item.
a) Enumerated lists may be nested.
b) Blank lines may be omitted between list items.
定义列表这样写
what
Definition lists associate a term with a definition.
how
The term is a one-line phrase, and the definition is one
or more paragraphs or body elements, indented relative to
the term.
表格
简单的表格既简单又紧凑
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
表格中必须至少有两列（以便与章节标题区分开来）。列跨度使用连字符下划线（“Inputs”跨越前两列）
===== ===== ======
Inputs Output
------------ ------
A B A or B
===== ===== ======
False False False
True False True
False True True
True True True
===== ===== ======
第一列单元格中的文本开始新的一行。第一列中没有文本表示续行；其余单元格可能由多行组成。例如
===== =========================
col 1 col 2
===== =========================
1 Second column of row 1.
2 Second column of row 2.
Second line of paragraph.
3 - Second column of row 3.
- Second item in bullet
list (row 3, column 2).
===== =========================
超链接
在 PEP 正文中引用外部网页时，您应该在文本中包含页面的标题或适当的描述，并带有内联超链接或带有 URL 的单独显式目标。不要在 PEP 正文文本中包含裸 URL，并尽可能使用 HTTPS 链接。
超链接引用使用反引号和后跟下划线来标记引用文本；如果引用文本是单个单词，则反引号是可选的。例如，要引用名为Python website的超链接目标，您将写
In this paragraph, we refer to the `Python website`_.
如果您打算只引用一个链接一次，并希望将其与文本内联定义，请将链接插入到您想要链接的文本后面的尖括号（<>）中，但在反引号之前，文本和左尖括号之间有一个空格。您还应该在右尖括号后面使用双下划线而不是单下划线，这使其成为匿名引用，以避免与其他目标名称冲突。例如
Visit the `website <https://pythonlang.cn/>`__ for more.
如果您想在多个地方使用一个链接，并使用不同的链接文本，或者想确保在更改链接文本时无需更新链接目标名称，请在链接文本后面（紧跟目标名称之后，但在右尖括号之前）用尖括号包含目标名称（否则链接将不起作用）。例如
For further examples, see the `documentation <pydocs_>`_.
显式目标提供 URL。将目标放在 PEP 末尾的脚注部分，或紧跟在包含引用的段落之后。超链接目标以两个句点和空格（“显式标记开始”）开头，后跟一个前导下划线、引用文本、一个冒号和 URL。
.. _Python web site: https://pythonlang.cn/
.. _pydocs: https://docs.pythonlang.cn/
引用文本和目标文本必须匹配（尽管匹配不区分大小写且忽略空格差异）。请注意，下划线位于引用文本之后，但位于目标文本之前。如果您将下划线视为向右的箭头，它会从引用指向目标。
内部链接和 PEP/RFC 链接
与超链接相同的机制可用于内部引用。每个唯一的章节标题隐式定义了一个内部超链接目标。我们可以像这样链接到摘要部分
Here is a hyperlink reference to the `Abstract`_ section. The
backquotes are optional since the reference text is a single word;
we can also just write: Abstract_.
要引用 PEP 或 RFC，请始终使用:pep:和:rfc:角色，切勿使用硬编码的 URL。例如
See :pep:`1` for more information on how to write a PEP,
and :pep:`the Hyperlink section of PEP 12 <12#hyperlinks>` for how to link.
这呈现为
有关如何编写 PEP 的更多信息，请参阅PEP 1，有关如何链接，请参阅PEP 12 的超链接部分。
文本中的 PEP 编号从不填充，并且“PEP”或“RFC”与编号之间有一个空格（不是破折号）；上述角色将为您处理。
脚注
脚注引用由左方括号、标签、右方括号和尾随下划线组成。不使用数字，而是使用“#word”形式的标签，其中“word”是助记符，由字母数字以及内部连字符、下划线和句点组成（不允许有空格或其他字符）。例如
Refer to The TeXbook [#TeXbook]_ for more information.
它渲染为
有关更多信息，请参阅 The TeXbook [1]。
脚注引用前必须有空格。在脚注引用和前面的单词之间留一个空格。
脚注用于额外的注释、解释和注意事项，以及引用不易在线获取的书籍和其他来源。应优先使用原生 reST 超链接目标或文本中的内联超链接来包含在线资源的 URL。
脚注以“.. ”（显式标记开始）开头，后跟脚注标记（无下划线），再后跟脚注正文。例如
.. [#TeXbook] Donald Knuth's *The TeXbook*, pages 195 and 196.
它渲染为
脚注和脚注引用将自动编号，并且编号将始终匹配。
图片
如果您的 PEP 包含图表或其他图形，您可以使用image指令将其包含在处理后的输出中
.. image:: diagram.png
任何浏览器友好的图形格式都是可能的；PNG 应优先用于图形，JPEG 用于照片，GIF 用于动画。目前，由于与 PEP 构建系统的兼容性问题，必须避免使用 SVG。
为了可访问性和源代码读者，您应该使用image指令的:alt:选项来包含图像的描述和其中包含的任何关键信息
.. image:: dataflow.png
:alt: Data flows from the input module, through the "black box"
module, and finally into (and through) the output module.
转义机制
reStructuredText 使用反斜杠（“\”）来覆盖标记字符的特殊含义并获取字面字符本身。要获取字面反斜杠，请使用转义反斜杠（“\\”）。在两种情况下，反斜杠没有特殊含义：字面块和内联字面（参见上面的内联标记）。在这些情况下，不进行标记识别，单个反斜杠表示字面反斜杠，而无需加倍。
如果您发现需要在文本中使用反斜杠，请考虑使用内联字面或字面块。
Intersphinx
您可以使用Intersphinx 引用到其他 Sphinx 站点，例如Python 文档packaging.python.org和typing.python.org，以便轻松地交叉引用页面、章节和 Python/C 对象。
例如，要创建指向类型文档某部分的链接，您可以编写以下内容
:ref:`type expression <typing:type-expression>`
规范文档
如PEP 1 所述，PEP 一旦被标记为“Final”，就被视为历史文档，其规范文档/规范应迁移到其他地方。为此，请使用canonical-doc指令或适当的子类
- 用于打包标准的
canonical-pypa-spec - 用于类型标准的
canonical-typing-spec
将指令添加在标题和 PEP 的第一部分（通常是摘要）之间，并将其规范文档/规范的 Intersphinx 引用（或者如果目标不在 Sphinx 站点上，则为 reST 超链接）作为参数传递。
例如，要创建指向sqlite3文档的横幅，您可以编写以下内容
.. canonical-doc:: :mod:`python:sqlite3`
这将生成横幅
或者对于 PyPA 规范，例如核心元数据规范，您将使用
.. canonical-pypa-spec:: :ref:`packaging:core-metadata`
它渲染为
对于不引入新运行时对象的类型 PEP，您可以使用这些中的第一个；对于引入新对象到运行时类型模块的类型 PEP，您可以使用第二个
.. canonical-typing-spec:: :ref:`typing:packaging-typed-libraries`
.. canonical-typing-spec:: :ref:`typing:literal-types` and
:py:data:`typing.Literal`
两者渲染为
该参数接受任意 reST，因此您可以包含多个链接文档/规范并随意命名它们，您还可以包含将插入到文本中的指令内容。以下高级示例
.. canonical-doc:: the :ref:`python:sqlite3-connection-objects` and :exc:`python:~sqlite3.DataError` docs
Also, see the :ref:`Data Persistence docs <persistence>` for other examples.
将渲染为
应避免的习惯
许多熟悉 TeX 的程序员经常这样书写引号
`single-quoted' or ``double-quoted''
反引号在 reStructuredText 中具有特殊含义，因此应避免这种做法。对于普通文本，请使用普通的“单引号”或“双引号”。对于内联字面文本（参见上面的内联标记），请使用双反引号
``literal text: in here, anything goes!``
建议的章节
PEP 1 中概述了 PEP 中常见的各种章节。为方便起见，此处提供了这些章节。
PEP: <REQUIRED: pep number>
Title: <REQUIRED: pep title>
Author: <REQUIRED: list of authors' names and optionally, email addrs>
Sponsor: <name of sponsor>
PEP-Delegate: <PEP delegate's name>
Discussions-To: Pending
Status: <REQUIRED: Draft | Active | Accepted | Provisional | Deferred | Rejected | Withdrawn | Final | Superseded>
Type: <REQUIRED: Standards Track | Informational | Process>
Topic: <Governance | Packaging | Release | Typing>
Requires: <pep numbers>
Created: <date created on, in dd-mmm-yyyy format>
Python-Version: <version number>
Post-History: <REQUIRED: dates, in dd-mmm-yyyy format, and corresponding links to PEP discussion threads>
Replaces: <pep number>
Superseded-By: <pep number>
Resolution: <url>
Abstract
========
[A short (~200 word) description of the technical issue being addressed.]
Motivation
==========
[Clearly explain why the existing language specification is inadequate to address the problem that the PEP solves.]
Rationale
=========
[Describe why particular design decisions were made.]
Specification
=============
[Describe the syntax and semantics of any new language feature.]
Backwards Compatibility
=======================
[Describe potential impact and severity on pre-existing code.]
Security Implications
=====================
[How could a malicious user take advantage of this new feature?]
How to Teach This
=================
[How to teach users, new and experienced, how to apply the PEP to their work.]
Reference Implementation
========================
[Link to any existing implementation and details about its state, e.g. proof-of-concept.]
Rejected Ideas
==============
[Why certain ideas that were brought while discussing this PEP were not ultimately pursued.]
Open Issues
===========
[Any points that are still being decided/discussed.]
Acknowledgements
================
[Thank anyone who has helped with the PEP.]
Footnotes
=========
[A collection of footnotes cited in the PEP, and a place to list non-inline hyperlink targets.]
Copyright
=========
This document is placed in the public domain or under the
CC0-1.0-Universal license, whichever is more permissive.
资源
还有许多其他结构和变体是可能的，包括基本Docutils支持的，以及Sphinx添加的扩展。
有许多资源可供您了解更多信息
- Sphinx ReStructuredText 入门，一份温和但相当详细的介绍。
- reStructuredText 标记规范，基本 reST 语法、指令、角色等的权威、全面的文档。
- Sphinx 角色和Sphinx 指令，Sphinx 文档系统用于将 PEP 渲染为 HTML 所添加的扩展结构。
如果您有疑问或需要帮助撰写上述资源未解决的 PEP，请在 GitHub 上联系@python/pep-editors，在PEPs 仓库上提出问题，或直接联系 PEP 编辑器。
版权
本文档置于公共领域或 CC0-1.0-Universal 许可证下，以更宽松者为准。
来源：https://github.com/python/peps/blob/main/peps/pep-0012.rst
评论
注释是紧跟在显式标记开始（两个句点和一个空格）之后的缩进文本块。将“..”单独留在一行上，以确保注释不会被误解为另一个显式标记结构。注释在处理后的文档中不可见。例如