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

Question

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

所有 reST 文件都使用 3 个空格的缩进；不允许使用标签。

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

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

关键是，这一切仍然有效！所以我想知道 3 空格缩进是否是必需的，或者它是否是一种好的做法，但仅在风格方面？ （如果是这样，为什么 Python 的所有东西都是 4 空格缩进的？）

或者在某些情况下没有 3 空格缩进会破坏我的构建？

我看过的其他地方

• Sphinx reStructuredText Primer 没有提到具体的空格数，只是：

  在 Python 中，缩进在 reST 中很重要，因此同一段落的所有行都必须左对齐到相同的缩进级别。

• 这个(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。