Sphinx: Sphinx: Indent with 2 spaces, except for toctree which is 3 spaces...

[yves-chevallier]

From the documentation. The toctree directive is the only one that requires a 3 space indentation. This looks like a glitch in the matrix and it should be fixed in some way.

Indentation
Indent with 2 spaces.

Except:

toctree directive requires a 3 spaces indentation.

Then I propose enforce what the doc says by adding an .editorconfig file that specifies 2 spaces for rST files.

What do you guys think?

[mgeier]

Isn't this just a random 3rd party page? That was last updated 8 years ago?

I guess you should open your issue at https://github.com/benoitbryon/documentation-style-guide-sphinx?

[yves-chevallier]

It is perhaps a random 3rd party page, but new projects created with sphinx-quickstart creates a 3 space indentation where it is more than standard to use 2 on JS, JSON and YAML and 4 on Python. So 3 is... kind on the fringes of programming habits...

I don't judge anything, but I would like to be consistent. If there is a technical reason why the toctree has to be 3 spaces, this issue has to be addressed here, otherwise it can be simply closed.

[yves-chevallier]

That said @mgeier you right I didn't see this page was a 3rd party one, but still is the question about the sphinx-quickstart indent.

If Python is 4 spaces, why would we have rST using 3 spaces ?

[mgeier]

If there is a technical reason why the toctree has to be 3 spaces

There is no technical reason because it's not true.
It can have any non-zero indentation.

So 3 is... kind on the fringes of programming habits...

Indeed, reST is strange ... but we love it nonetheless!

I would like to be consistent

AFAICT, docutils and Sphinx are quite consistent in using 3 spaces in their documentation.

If you find other indentations in the official docs, you should feel free to make a PR to fix it.

If Python is 4 spaces, why would we have rST using 3 spaces ?

I have no idea. But if I had to guess, I would say it's maybe because the .. prefix in directives is three characters long?

.. note::

   This line starts directly below "note".

So perhaps the creators of reST (or at least those writing the docs) found that aesthetically pleasing?

Anyway, they are allowing arbitrary indentation, so authors can choose for themselves whatever indentation they prefer.

I personally often prefer 4 spaces because I work a lot with Python code blocks, so I think it's nice to have the same reST and Python indentation.

But in some projects (with less Python code) I indeed use 3 spaces, because that seems to be the traditional way to do it.

[yves-chevallier]

You convinced me with the painful ..prefix is three characters long...

[tk0miya]

Yes, that is why we use 3 spaces for indent of directives. To be exact, reStructuredText does not expect the indent must be 3. We can use any counts of spaces (one or more) for the indent.

So this is valid reST:

.. note::

 blah

This is also:

.. note::

                      blah

Additionally, there is no special rules only for toctree directive. It is also accepts one or more spaces as its indent.

[mgeier]

But we could still add an .editorconfig file with:

[*.rst]
indent_size = 3

This would make the intention more explicit, I guess.

[tk0miya]

Unfortunately, no. The indentation of reStructuredText is dynamically changed. Let's take a look into bullet lists and enumerated lists.

* The indentation of bullet list is
  just 2 spaces.

   If you use 3 spaces, it will be parsed as block quotes.
   https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#block-quotes


*  To be accurate, the reST parser considers the indentation-depth of the first line of
   list item is a baseline of the paragraph.

   In this case, 3 spaces are need to be a part of the list item.

  This line, indented by 2 spaces, is a block quote after the bullet list.

1. For enumerated lists, reST parser also applied same indentation-rule (baseline rule).
   So 3 spaces are needed for enumerated lists basically (num + dot + space).

10. Sadly, 4 spaces are needed
    for two digits list-items!

1000. Additionally, more spaces are
      needed here!

(a) If you use numbers with parens for enumerated list,
    you need to use 4 (or more) spaces for indentation
    because it is one level deeper than dotted-number (ex `a.`)

I think it is hard to support the indents of reST by single indentation rule.