为什么定义在 NumPy 文档字符串部分的冒号前有一个 space？
Why do definitions have a space before the colon in NumPy docstring sections?
The colon must be preceded by a space, or omitted if the type is absent.
并举个例子：
Parameters
----------
x : type
Description of parameter `x`.
y
Description of parameter `y` (with type not specified)
另一方面，
PEP8字面意思是冒号前的space是错误的：
# Wrong:
code:int # No space after colon
code : int # Space before colon
我知道这适用于代码，不适用于文档字符串，但为什么不保持一致？
问题
在冒号前加上space的动机是什么？
它似乎违反了排版规则以及 python 约定（或至少是直觉）。
Why a space before the colon?
因为在NumPy里面有一些语法定义docstring sections are made to coincide with the syntax of a reStructuredText Definition List。
请注意语法与 reST 标记规范完全相同：
Each definition list item contains a term, optional classifiers, and a definition. A term is a simple one-line word or phrase. Optional classifiers may follow the term on the same line, each after an inline " : " (space, colon, space).
Syntax diagram:
+----------------------------+
| term [ " : " classifier ]* |
+--+-------------------------+--+
| definition |
| (body elements)+ |
+----------------------------+
有道理，因为 numpydoc 清楚地说明了它打算遵守 PEP 257。
numpydoc docstring guide
We mostly follow the standard Python style conventions as described here:
- Docstring Conventions - PEP 257
并且 PEP 表明其意图是应该使用 reST 结构编写文档字符串：
This PEP proposes that the reStructuredText markup be adopted as a standard markup format for structured plaintext documentation in Python docstrings
这也可以通过引用 numpydoc 贡献者的决定来验证，例如：
Right now numpydoc format is actually valid rst (just with some special interpretation of certain markup constructs), e.g. the parameters field is a definition list where the type is a "classifier" (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#definition-lists). I would argue that it is worthwhile to keep this property, which end-of-line backslashes do (they simply do not appear in the string itself), whereas the proposed "recognize indentation" syntax does not.
相同的推理在多处提到：
This probably falls under the category of "if it ain't broke, don't fix it", but I note that we're strangely using blockquotes for parameter listings instead of definition lists. UPDATED: now this PR proposes to use definition lists by default, with a switch to use the legacy blockquotes.
冒号前一个space的具体规则可以在numpydoc.validate.py源代码中看到，在文档中：
"PR10": 'Parameter "{param_name}" requires a space before the colon '
"separating the parameter name and type"
总而言之，要使用 reST 编写文档字符串（以符合 PEP 257），reST Body Elements 中没有太多列表标记结构可供选择。定义列表是最好的选择，因为它的 term/classifier 语法完全适合 Python 对象的 name/type 列表。
解决问题中提出的直觉异议：
In the other hand, PEP8 literally says that a space before colon is wrong
是的，但是 PEP 8 提到的函数和变量注释不是指文档字符串 (docstrings)！这些用于签名和变量声明。
The colon must be preceded by a space, or omitted if the type is absent.
并举个例子：
Parameters
----------
x : type
Description of parameter `x`.
y
Description of parameter `y` (with type not specified)
另一方面， PEP8字面意思是冒号前的space是错误的：
# Wrong:
code:int # No space after colon
code : int # Space before colon
我知道这适用于代码，不适用于文档字符串，但为什么不保持一致？
问题
在冒号前加上space的动机是什么？
它似乎违反了排版规则以及 python 约定（或至少是直觉）。
Why a space before the colon?
因为在NumPy里面有一些语法定义docstring sections are made to coincide with the syntax of a reStructuredText Definition List。 请注意语法与 reST 标记规范完全相同：
Each definition list item contains a term, optional classifiers, and a definition. A term is a simple one-line word or phrase. Optional classifiers may follow the term on the same line, each after an inline " : " (space, colon, space).
Syntax diagram: +----------------------------+ | term [ " : " classifier ]* | +--+-------------------------+--+ | definition | | (body elements)+ | +----------------------------+
有道理，因为 numpydoc 清楚地说明了它打算遵守 PEP 257。
numpydoc docstring guide
We mostly follow the standard Python style conventions as described here:
- Docstring Conventions - PEP 257
并且 PEP 表明其意图是应该使用 reST 结构编写文档字符串：
This PEP proposes that the reStructuredText markup be adopted as a standard markup format for structured plaintext documentation in Python docstrings
这也可以通过引用 numpydoc 贡献者的决定来验证，例如：
Right now numpydoc format is actually valid rst (just with some special interpretation of certain markup constructs), e.g. the parameters field is a definition list where the type is a "classifier" (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#definition-lists). I would argue that it is worthwhile to keep this property, which end-of-line backslashes do (they simply do not appear in the string itself), whereas the proposed "recognize indentation" syntax does not.
相同的推理在多处提到：
This probably falls under the category of "if it ain't broke, don't fix it", but I note that we're strangely using blockquotes for parameter listings instead of definition lists. UPDATED: now this PR proposes to use definition lists by default, with a switch to use the legacy blockquotes.
冒号前一个space的具体规则可以在numpydoc.validate.py源代码中看到，在文档中：
"PR10": 'Parameter "{param_name}" requires a space before the colon ' "separating the parameter name and type"
总而言之，要使用 reST 编写文档字符串（以符合 PEP 257），reST Body Elements 中没有太多列表标记结构可供选择。定义列表是最好的选择，因为它的 term/classifier 语法完全适合 Python 对象的 name/type 列表。
解决问题中提出的直觉异议：
In the other hand, PEP8 literally says that a space before colon is wrong
是的，但是 PEP 8 提到的函数和变量注释不是指文档字符串 (docstrings)！这些用于签名和变量声明。