[issue42496] Don't change indentation of RST markup

[Raymond Hettinger]

New submission from Raymond Hettinger <raymond.hettinger at gmail.com>:

I just noticed that this PR was applied:  https://github.com/python/cpython/pull/23545

In general, I don't think this should be done.  AFAICT, it has no visual effect for the reader and that the current markup is allowed by Sphinx (i.e. this isn't a bug and "fix markup" inaccurately indicated that something is being fixed).

Looking the Sphinx docs, the only rule I see is "Options must be indented to the same level as the directive content."

Given that the markup isn't wrong, I suggest that it be left alone:

* Changing it is unnecessary churn
* It makes back-porting real doc fixes more difficult
* It messes-up the blame/annotate history
* Presumably, the original author did it for their convenience (editors sets to four space indents, etc.)

In the Sphinx world, three space indents are the norm.  In the Python world, four space indents are the norm.  Given that Sphinx allows either, I think we should respect what the original author found that made sense for them.

For example, in the descriptor tutorial, I used four-space indented content for doctest/codetest directives to make maintenance easier (I can cut and paste fragments from live, tested code).

----------
assignee: docs at python
components: Documentation
messages: 382030
nosy: adelfino, docs at python, gregory.p.smith, rhettinger
priority: normal
severity: normal
status: open
title: Don't change indentation of RST markup
versions: Python 3.10

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue42496>
_______________________________________