Move markup concerns from style to markup #1292
Conversation
d471d33 to
78e8b34
Compare
documentation/markup.rst
Outdated
| Use of whitespace | ||
| ----------------- | ||
|
|
||
| All reST files use an indentation of 3 spaces; no tabs are allowed. The | ||
| maximum line length is 80 characters for normal text, but tables, deeply | ||
| indented code samples and long links may extend beyond that. Code example | ||
| bodies should use normal Python 4-space indentation. | ||
|
|
||
| Make generous use of blank lines where applicable; they help group things | ||
| together. | ||
|
|
||
| A sentence-ending period may be followed by one or two spaces. While reST | ||
| ignores the second space, it is customarily put in by some users, for example | ||
| to aid Emacs' auto-fill mode. |
There was a problem hiding this comment.
The first paragraph is indeed about the technical rules of reST markup. However, the second is about writing style. The last seems a bit of a mix, but really about reST.
I don't mind them all being moved here, if there's no good place for the second one in the style guide.
There was a problem hiding this comment.
The second and third paragraphs are only about the .rst files: blank lines and extra spaces aren't rendered into the output. These guidelines don't affect what the reader sees, so they belong in the markup concerns.
There was a problem hiding this comment.
Ah, does the second just mean single line breaks (\n)?
Like this:
An expression-less :keyword:`!except` clause, if present, must be last; it matches any
exception. For an :keyword:`!except` clause with an expression, that expression is
evaluated, and the clause matches the exception if the resulting object is "compatible"
with the exception. An object is compatible with an exception if the object is the
class or a :term:`non-virtual base class <abstract base class>` of the exception object,
or a tuple containing an item that is the class or a non-virtual base class of the
exception object.Is indeed rendered the same as:
An expression-less :keyword:`!except` clause, if present, must be last;
it matches any exception.
For an :keyword:`!except` clause with an expression,
that expression is evaluated, and the clause matches the exception
if the resulting object is "compatible" with the exception. An object is
compatible with an exception if the object is the class or a
:term:`non-virtual base class <abstract base class>` of the exception object,
or a tuple containing an item that is the class or a non-virtual base class
of the exception object.Or is it talking about new empty lines (\n\n)? Because if I add extra empty lines here, this is rendered as multiple paragraphs, which is style:
An expression-less :keyword:`!except` clause, if present, must be last;
it matches any exception.
For an :keyword:`!except` clause with an expression,
that expression is evaluated, and the clause matches the exception
if the resulting object is "compatible" with the exception.
An object is
compatible with an exception if the object is the class or a
:term:`non-virtual base class <abstract base class>` of the exception object,
or a tuple containing an item that is the class or a non-virtual base class
of the exception object.There was a problem hiding this comment.
I think the second paragraph could be in the style guide. The first and third belong in markup. If we want to mention space after a sentence in the style guide, we should recommend one space for any new docs.
There was a problem hiding this comment.
Because of they help group things together, I interpreted this advice as encouraging people to sometimes use two blank lines instead of just one if it would make the structure of the document clearer.
There was a problem hiding this comment.
We could call it something different than whitespace.
There was a problem hiding this comment.
I still think this paragraph is about the reST file, not the text as visible to the reader. I've changed it to:
Make use of multiple blank lines where applicable to clarify the structure of
the reST file. Extra blank lines help group sections together to make the
organization of the file clearer.
There was a problem hiding this comment.
Multiple blank lines do make a difference to the text as visible to the reader.
Here's the three chunks above, rendered.
-
ONE and TWO are the same except for single newlines, and are the same for the reader.
-
But THREE has multiple newlines and they become paragraphs.
There was a problem hiding this comment.
Yes, but one and two don't differ in the number of blank lines. They differ in the number of newlines. They have no blank lines.
I understand the value of wisely choosing paragraph breaks. I don't think that's what this text was about.
There was a problem hiding this comment.
Okay, if that's the case, then we agree.
A bit of archaeology, seems this wasn't in 2.5 and was added in 2.6, which incidentally is when the docs were converted from Latex to reST.
As it happens, the CPython style guide used to recommend primarily following the Apple Publications Style Guide, but that advice was removed when the link broke (python/cpython#62221). Here's an archived copy, and Apple's current style guide. Not suggesting we reinstate it, just sharing some history :)
58b7330 to
dbdbe5d
Compare
dbdbe5d to
da07519
Compare
There was a problem hiding this comment.
FTR this page was initially copied from https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html. I don't think your additions are a problem though, since it has already diverged from the original over the years.
I'm preparing to add more linguistic style to the style guide. These two sections are about the logistics of .rst files, so I'm moving them to the markup page.
📚 Documentation preview 📚: https://cpython-devguide--1292.org.readthedocs.build/