PEP 12 – reStructuredText PEP 模板示例
- 作者:
- David Goodger <goodger at python.org>, Barry Warsaw <barry at python.org>, Brett Cannon <brett at python.org>
- 状态:
- 活跃
- 类型:
- 流程
- 创建:
- 2002-08-05
- 发布历史:
- 2002-08-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 以了解详细信息，或在 PEPs 仓库中打开一个跟踪器问题以寻求帮助。
确定你自己的 PEP 类型后，请按照以下说明进行操作。
- 复制此文件（
.rst文件，**不是** HTML 文件！）并进行以下编辑。将新文件命名为pep-NNNN.rst，使用下一个可用数字（不要与已发布或正在 PR 中的 PEP 使用的数字重复）。 - 将“PEP: 12”标题替换为“PEP: NNNN”，使其与文件名匹配。请注意，文件名应该用零填充（例如
pep-0012.rst），但标题不应该（PEP: 12）。 - 将标题标题更改为你的 PEP 的标题。
- 将作者标题更改为包含你的姓名，以及可选的电子邮件地址。确保仔细遵循格式：你的姓名必须先出现，并且不能放在括号中。你的电子邮件地址可以出现在第二位（也可以省略），如果出现，它必须出现在尖括号中。可以对你的电子邮件地址进行模糊处理。
- 如果所有作者都不是 Python 核心开发人员，则在赞助者标题下包含赞助你 PEP 的核心开发人员的姓名。
- 在讨论主题标题下添加 PEP 规范讨论线程的直接 URL（例如在 Python-Dev、Discourse 等上）。如果该线程将在 PEP 作为官方草案提交后创建，则最初只列出场地名称即可，但请记住，一旦 PEP 成功合并到 PEPs 仓库并且你创建了相应的讨论线程，请尽快使用 URL 更新 PEP。有关详细信息，请参阅 PEP 1。
- 将状态标题更改为“草案”。
- 对于标准追踪 PEP，将类型标题更改为“标准追踪”。
- 对于信息性 PEP，将类型标题更改为“信息性”。
- 对于标准追踪 PEP，如果你的功能依赖于其他正在开发的 PEP 的接受，请在类型标题之后添加一个依赖标题。该值应该是你依赖的 PEP 的 PEP 号码。如果你的依赖功能在最终 PEP 中描述，则不要添加此标题。
- 将创建标题更改为今天的日期。确保仔细遵循格式：它必须采用
dd-mmm-yyyy格式，其中mmm是 3 个英文字母的月份缩写，即 Jan、Feb、Mar、Apr、May、Jun、Jul、Aug、Sep、Oct、Nov、Dec 之一。 - 对于标准追踪 PEP，在创建标题之后，添加一个 Python 版本标题，并将该值设置为下一个计划的 Python 版本，即你的新功能有望首次出现在该版本中。不要在此处使用 alpha 或 beta 版本指定。因此，如果 Python 的最后一个版本是 2.2 alpha 1，并且你希望在 Python 2.2 中添加你的新功能，请将标题设置为
Python-Version: 2.2
- 如果 PEP 属于 主题索引 中显示的主题之一，请添加一个主题标题。大多数 PEP 都不属于。
- 暂时保留发布历史，你将在每次将 PEP 发布到指定的讨论论坛时（并如上所述，使用该链接更新讨论主题标题）在此标题下添加日期和相应的链接。对于每个线程，使用日期（采用
dd-mmm-yyy格式）作为链接文本，并将 URL 作为匿名 reST 超链接 内联插入，并在每个帖子之间使用逗号隔开。如果你在 2001 年 8 月 14 日和 2001 年 9 月 3 日发布了有关 PEP 的线程，则发布历史标题将如下所示，例如
Post-History: `14-Aug-2001 <https://www.example.com/thread_1>`__, `03-Sept-2001 <https://www.example.com/thread_2>`__
你应该在发布新的讨论线程后立即在此处添加新的日期/链接。
- 如果你的 PEP 弃用了之前的 PEP，请添加一个替换标题。此标题的值是被你新 PEP 替换的 PEP 的号码。仅当旧 PEP 为“最终”形式时才添加此标题，即已接受、最终或被拒绝。如果你提交的是一个竞争想法，则不会替换旧的开放 PEP。
- 现在编写你的摘要、基本原理和其他内容，用你自己的文本替换所有这些乱七八糟的内容。确保遵循以下格式指南，特别是关于禁止使用制表符和缩进要求的规定。有关要包含的章节模板，请参阅下面的“建议的章节”。
- 更新你的脚注部分，列出文本引用的所有脚注和非内联链接目标。
- 运行
./build.py以确保 PEP 渲染时没有错误，并检查build/pep-NNNN.html中的输出是否符合你的预期。 - 针对 PEPs 仓库 创建拉取请求。
作为参考，以下是所有可能的标题字段（方括号中的所有内容都应该被替换，或者如果它具有一个以 * 开头的标记，表示它是可选的，并且它不适用于你的 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，请使用 .. highlight:: language 指令，并在 PEP 文档开头（在标题和摘要之间）使用相应的 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.
这将渲染为
有关更多信息，请参阅 [1] 的 The TeXbook。
脚注引用之前必须有空格。在脚注引用和前面的词语之间留一个空格。
使用脚注来添加注释、解释和注意事项，以及引用书籍和其他不易在线获取的资料。对于包含指向在线资源的 URL，应优先使用本地 reST 超链接目标或文本中的内联超链接，而不是脚注。
脚注以 “.. “ 开头（显式标记开始），后跟脚注标记（无下划线），然后是脚注主体。例如
.. [#TeXbook] Donald Knuth's *The TeXbook*, pages 195 and 196.
这将渲染为
脚注和脚注引用将自动编号，并且编号始终匹配。
图像
如果您的 PEP 包含图表或其他图形，您可以使用 image 指令在处理后的输出中包含它
.. image:: diagram.png
任何浏览器友好的图形格式都可以，PNG 应优先用于图形，JPEG 用于照片，GIF 用于动画。目前，由于与 PEP 构建系统的兼容性问题，必须避免使用 SVG。
为了可访问性和源文本的阅读者，您应该使用 :alt: 选项对 image 指令包含图像和图像中包含的任何关键信息的描述
.. 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.readthedocs.io，以轻松交叉引用页面、章节和 Python/C 对象。
例如，要创建指向 typing 文档部分的链接，您需要编写以下代码
:ref:`type expression <typing:type-expression>`
规范文档
正如 PEP 1 所描述的，一旦 PEP 被标记为最终版，它们就被认为是历史文档，其规范文档/规范应移至其他地方。要指示这一点，请使用 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，您可能使用以下内容中的第一个；对于在运行时向 typing 模块引入新对象的类型 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 中发现许多常见的部分，它们在 PEP 1 中有所概述。为了方便起见，这里提供了这些部分。
PEP: <REQUIRED: pep number>
Title: <REQUIRED: pep title>
Author: <REQUIRED: list of authors' real names and optionally, email addrs>
Sponsor: <real name of sponsor>
PEP-Delegate: <PEP delegate's real name>
Discussions-To: <REQUIRED: URL of current canonical discussion thread>
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.]
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 上 ping @python/pep-editors，在 PEPs 存储库中打开一个问题 或直接联系 PEP 编辑。
版权
本文件归属公共领域或 CC0-1.0-Universal 许可证，以更宽松的许可为准。
来源：https://github.com/python/peps/blob/main/peps/pep-0012.rst
上次修改时间：2024-06-14 23:31:40 GMT
注释
注释是紧随显式标记开始的任意文本的缩进块：两个句点和空格。将 “..” 单独放在一行上，以确保注释不被误解为其他显式标记结构。注释在处理后的文档中不可见。例如