问题
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.
回答1:
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.
- Choose a style and keep it consistent for your documentation.
- IDEs often complain about incorrect indentation, like for docstrings in Python, so using 4 spaces can avoid those warnings.
- IDEs can be set to indent to 4 spaces for code, so why not keep it the same for documentation?
- See my bonus tip about indenting for numbered lists.
来源：https://stackoverflow.com/questions/48311159/is-3-space-indentation-required-in-rest