17

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

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.

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Tim
  • 1,839
  • 10
  • 18
  • 1
    The 3-space rule you're citing is from a style guide. It's one project's style rule. – user2357112 Jan 17 '18 at 22:40
  • Okay, so is the "project" here official Python documentation? As in, it's the style guide for documentation on docs.python.org? – Tim Jan 19 '18 at 10:03
  • Yes. You're reading the guide for developers working on Python itself. – user2357112 Jan 19 '18 at 17:23
  • 1
    I have found (by trial and error due to lack of strict specification) that directives with content require content to be indented by exactly 3 spaces. 2 spaces and content is not recognized as a part of the directive; 4 spaces and content is treated as if every line started with a space. This is really annoying for `code` and other text-display directives because stuff itself has 4-space indent while beginning indent must be 3. – Xeverous May 29 '21 at 13:29

1 Answers1

18

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.
Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • I know the advice says to "avoid comments like 'thanks' ", but this is my first SO question, so...thanks for the advice, and that bonus tip for numbered lists is great! (I appreciate that it both makes working with 4-space indents easier, and gives consistency to the look for no.s 10-99) – Tim Jan 19 '18 at 10:06