python - reST 中是否需要 3 个空格缩进？

Question

我正在使用 Sphinx 记录我的 Python 代码，并阅读 in the Python developer's guide (我认为其他地方也是如此)reST 文件使用 3 个空格的缩进:

All reST files use an indentation of 3 spaces; no tabs are allowed.

这是我为索引文件复制的示例，以及我的 IDE 选择 3 个空格缩进并将其用于整个页面的其他一些文件的情况。 sphinx-apidoc 扩展还为它构建的 modules.rst 文件使用了 3 个空格。

另一方面，因为 Python 使用 4 个空格缩进，所以我所有的文档字符串都缩进了 4 个空格。此外，由 sphinx-apidox 生成的 .. automodule:: 指令缩进了 4 个空格。

重点是，它仍然有效!所以我想知道 3 个空格的缩进是否是必需的，或者它是否是一种很好的做法，但只是在风格方面？ (如果是这样，为什么，当所有 Python 都是 4 空格缩进的时候？)

或者是否存在没有 3 个空格缩进会破坏我的构建的情况？

我看过的其他地方

• Sphinx reStructuredText Primer没有提到具体数量的空间，只有:

  As in Python, indentation is significant in reST, so all lines of the same paragraph must be left-aligned to the same level of indentation.

• 这(unanswered) SO question ，具体是关于列表，而不是一般的间距
• reStructuredText Markup Specification引用footnotes只提到了3个空格.
• 这issue on GitHub ，虽然我认为这里的问题是不同元素的缩进级别的混合。

---

我开始认为 Python 开发人员指南可能是异常的，而不是其他任何东西，特别是因为在我所有的搜索中我发现基本上没有讨论工作时的“3 或 4 空间问题”使用 Sphinx 和 Python。

Answer 1

正如您通过研究权威来源和其他地方发现的那样，除了选项列表至少 2 个空格和脚注至少 3 个空格之外，没有明确的缩进规范。请参阅 specification on indentation for reStructuredText。

也就是说，有一些建议。

1. 选择一种样式并使其与您的文档保持一致。
2. IDE 经常提示缩进不正确，例如 Python 中的文档字符串，因此使用 4 个空格可以避免这些警告。
3. IDE 可以设置为代码缩进 4 个空格，那么为什么不在文档中保持相同的缩进呢？
4. 查看我的 bonus tip about indenting for numbered lists。