classification
Title: Don't change indentation of RST markup
Type: Stage: resolved
Components: Documentation Versions: Python 3.10
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: adelfino, docs@python, georg.brandl, gregory.p.smith, mark.dickinson, rhettinger, serhiy.storchaka
Priority: normal Keywords:

Created on 2020-11-29 02:25 by rhettinger, last changed 2020-11-29 13:35 by adelfino. This issue is now closed.

Messages (6)
msg382030 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-11-29 02:25
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).
msg382031 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-11-29 02:32
If this does have a visual effect for readers or if it breaks strict Sphinx requirement, let me know.
msg382043 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2020-11-29 07:48
Original PR: https://github.com/python/cpython/pull/23524

I just checked, it has a visual effect for readers. For example:

"""
BUILD_STRING(count)

    Concatenates count strings from the stack and pushes the resulting string onto the stack.

    New in version 3.6.

LIST_TO_TUPLE

        Pops a list from the stack and pushes a tuple containing the same values.

    New in version 3.9.

LIST_EXTEND(i)

    Calls list.extend(TOS1[-i], TOS). Used to build lists.

    New in version 3.9.
"""

One extra space added large indentation.
msg382046 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-11-29 08:40
Thanks for checking.
msg382053 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2020-11-29 11:36
To be clear, this has nothing to do with the amount of indentation, but that the directive below (the versionadded) has 4 spaces, and the paragraph above had 5 before the change. Therefore the further-indented paragraph is taken as a blockquote.
msg382062 - (view) Author: Andrés Delfino (adelfino) * (Python triager) Date: 2020-11-29 13:35
When I open a PR fixing mark-up it's because it has visual effects.
History
Date User Action Args
2020-11-29 13:35:22adelfinosetmessages: + msg382062
2020-11-29 11:36:53georg.brandlsetnosy: + georg.brandl
messages: + msg382053
2020-11-29 09:49:05mark.dickinsonsetnosy: + mark.dickinson
2020-11-29 08:40:09rhettingersetstatus: open -> closed
resolution: not a bug
messages: + msg382046

stage: resolved
2020-11-29 07:48:39serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg382043
2020-11-29 02:32:06rhettingersetmessages: + msg382031
2020-11-29 02:25:44rhettingercreate