reST 中是否需要 3 个空格的缩进? [英] Is 3-space indentation required in reST?

问题描述

我正在使用 Sphinx 记录我的 Python 代码，并阅读 Python 开发人员指南中的a>(我认为在其他地方也是如此)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 中的缩进很重要，因此同一段落的所有行都必须左对齐到相同的缩进级别.

• 这个(未回答的)SO 问题，具体是关于列表，而不是一般的间距
• reStructuredText 标记规范仅提及了 3 个空格作为参考脚注.
• 这个GitHub 上的问题，尽管我认为这里的问题是不同元素的缩进级别的混合.

<小时>

我开始认为 Python 开发人员指南可能是异常，而不是其他所有内容，特别是因为在我所有的搜索中，我在工作时基本上没有遇到关于3 或 4 空间问题"的讨论使用 Sphinx 和 Python.

解决方案

正如您通过对权威来源和其他地方的研究发现的那样，没有明确的缩进规范，除了选项列表至少有 2 个空格，以及一个脚注最少 3 个空格.请参阅有关 reStructuredText 缩进的规范.

也就是说，有一些建议.

1. 选择一种样式并使其与您的文档保持一致.
2. IDE 经常抱怨不正确的缩进，例如 Python 中的文档字符串，因此使用 4 个空格可以避免这些警告.
3. 可以将 IDE 设置为代码缩进 4 个空格，那么为什么不为文档保持相同的格式呢?
4. 请参阅我的关于缩进编号列表的额外提示.

I'm documenting my Python code using Sphinx, and read in the Python developer's guide (and I think elsewhere as well) that reST files use an indentation of 3 spaces:

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

This is the case for the example I copied for my index file, and some other files where my IDE picked up the 3-space indentation and used it for the whole page. The sphinx-apidoc extension also uses 3 spaces for the modules.rst file it builds.

On the other hand, because Python uses 4-space indentation, all my docstrings are indented with 4 spaces. Moreover the .. automodule:: directives generated by sphinx-apidox are indented with 4 spaces.

The point is, it all still works! So I'm left wondering whether the 3-space indentation thing is a requirement, or if it's good practice, but only in terms of style? (And if so, why, when all things Python are 4-space indented?)

Or are there cases where not having 3-space indentation will break my build?

Other places I've looked

• The Sphinx reStructuredText Primer doesn't mention a specific number of spaces, only:

  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.

• This (unanswered) SO question, which is about lists specifically, not spacing generally
• The reStructuredText Markup Specification only mentions 3 spaces in reference to footnotes.
• This issue on GitHub, though I think this issue here is the mixture of indentation levels for different elements.

---

I'm beginning to think the Python developer's guide might be the anomaly, rather than everything else, especially since in all my searching I've come across basically no discussion of the "3-or-4 space problem" when working with Sphinx and Python.

解决方案

As you have found through your research of the authoritative source and elsewhere, there is no definitive indentation specification, except a minimum of 2 spaces for option lists, and a minimum of 3 spaces for footnotes. See the specification on indentation for reStructuredText.

That said, there are some recommendations.

1. Choose a style and keep it consistent for your documentation.
2. IDEs often complain about incorrect indentation, like for docstrings in Python, so using 4 spaces can avoid those warnings.
3. IDEs can be set to indent to 4 spaces for code, so why not keep it the same for documentation?
4. See my bonus tip about indenting for numbered lists.

这篇关于reST 中是否需要 3 个空格的缩进?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！