Produce clear guidelines about indentation

[benoitbryon]

Issues with 2 spaces:

1. It's a pain to have several indentation levels in a same RST document while editing it, because the TAB shorcut gives wrong results.
   As an example toctree directive doesn't work with 2 spaces but seems to work with 3 or 4 spaces.
2. in code-blocks, it's a pain to deal with mixed indentation.
   As an example:

The following block is indented with 2 spaces.
.. code-block:: python

  def some_intendation():
      """This comment is indented with 4 spaces."""

Python convention is to use 4 spaces. Since most Sphinx projects are about Python projects, Python code-blocks are a really common use case. So 4 space indentation may be useful for many users (most of them?).

Another common use case for code-blocks is sh or bash... 4 spaces doesn't hurt in that case.

[benoitbryon]

Maybe a solution would be to make editors use "contextual indentation" (2 spaces in general case, 3 within toctree context, 2 then 4 within Python code-blocks, 2 then 2 within Drupal code-blocks, 2 then TAB within Makefile code-blocks...).
But I'm not sure it's easy to implement.
Moreover, as an human, it may not be easy to remember such a convention.

[benoitbryon]

4 spaces indentation is not a solution for all cases...

As examples:

Bullet lists use 2 spaces indentation:

* a first list item.
* a list item which
  is two lines long.

Numbered lists use 3 spaces indentation:

1. something
   which is long.
2. another thing.

I guess it is a feature to improve readability...

[benoitbryon]

Original RST indentation rules are here : http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#indentation

[benoitbryon]

See also PEP 12, which tells 4 spaces-indentation for literal blocks.

[yves-chevallier]

I don't agree with what you said... Numbered lists can use 4 spaces indentation, even five !

10. something
    which is long.
1000. another thing
      which can be longer...

If Python has 4 indent so is rST... Isn't?