[issue42496] Don't change indentation of RST markup

[Andrés Delfino]

Andrés Delfino  added the comment:

When I open a PR fixing mark-up it's because it has visual effects.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42496] Don't change indentation of RST markup

[Georg Brandl]

Georg Brandl  added the comment:

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.

--
nosy: +georg.brandl

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42496] Don't change indentation of RST markup

[Mark Dickinson]

Change by Mark Dickinson :


--
nosy: +mark.dickinson

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42496] Don't change indentation of RST markup

[Raymond Hettinger]

Raymond Hettinger  added the comment:

Thanks for checking.

--
resolution:  -> not a bug
stage:  -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42496] Don't change indentation of RST markup

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:

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.

--
nosy: +serhiy.storchaka

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42496] Don't change indentation of RST markup

[Raymond Hettinger]

Raymond Hettinger  added the comment:

If this does have a visual effect for readers or if it breaks strict Sphinx 
requirement, let me know.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42496] Don't change indentation of RST markup

[Raymond Hettinger]

New submission from Raymond Hettinger :

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@python
components: Documentation
messages: 382030
nosy: adelfino, docs@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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com