Is 3-space indentation required in reST?

Question

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.

Answer 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.

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.