[docs] Standardize documentation whitespace, formatting (issue 23921)

[storchaka at gmail.com]

http://bugs.python.org/review/23921/diff/14500/Doc/faq/design.rst
File Doc/faq/design.rst (right):

http://bugs.python.org/review/23921/diff/14500/Doc/faq/design.rst#newcode161
Doc/faq/design.rst:161: # ... do something with line
No need to swap ... and #. It is better to follow common style in
examples and "...  #" has advantages over "# ...".

http://bugs.python.org/review/23921/diff/14500/Doc/faq/library.rst
File Doc/faq/library.rst (right):

http://bugs.python.org/review/23921/diff/14500/Doc/faq/library.rst#newcode260
Doc/faq/library.rst:260: for i in range(n):
Trailing space.

http://bugs.python.org/review/23921/diff/14500/Doc/faq/library.rst#newcode277
Doc/faq/library.rst:277: for i in range(n):
Trailing space.

http://bugs.python.org/review/23921/diff/14500/Doc/faq/library.rst#newcode747
Doc/faq/library.rst:747: 
Trailing spaces.

http://bugs.python.org/review/23921/diff/14500/Doc/faq/programming.rst
File Doc/faq/programming.rst (right):

http://bugs.python.org/review/23921/diff/14500/Doc/faq/programming.rst#newcode1106
Doc/faq/programming.rst:1106: # ... do something with x ...
Previous code was syntactically correct, new code is not
(IndentationError: expected an indented block), because a comment is not
a statement.

http://bugs.python.org/review/23921/diff/14500/Doc/faq/programming.rst#newcode1114
Doc/faq/programming.rst:1114: # ... do something with x ...
Same as above.

http://bugs.python.org/review/23921/diff/14500/Doc/howto/curses.rst
File Doc/howto/curses.rst (right):

http://bugs.python.org/review/23921/diff/14500/Doc/howto/curses.rst#newcode182
Doc/howto/curses.rst:182: (height, width)    = (5, 40)
On 2015/04/12 19:55:06, jedwards wrote:
> On 2015/04/12 11:17:30, berkerpeksag wrote:
> > () is not needed:
> > 
> >     begin_x, begin_y = (20, 7)
> > 
> > is a valid Python code.
> 
> This was the most substantiate change I made in the patch -- I believe
it was
> the only place where I violated my rule of "whitespace only". 
> 
> I wrapped the LHS in parens in an attempt to make it more
new-user-friendly.
> 
> I originally has what you wrote:
> 
> a, b = (c, d)
> 
> But, after looking at it, I was afraid that new users would get this
confused
> with 
> 
> a = b = (c, d)
> 
> This concern may not be founded of course, but just explaining the
thought
> process behind the change.

I prefer more clean

    a, b = c, d

if multitarget assignment is used. This is one of nicer features of
Python and no one Python user should be confused by it.

But in this case it may be better to left original code with multiple
assignments. At least let don't change this in this patch.

http://bugs.python.org/review/23921/diff/14500/Doc/howto/descriptor.rst
File Doc/howto/descriptor.rst (right):

http://bugs.python.org/review/23921/diff/14500/Doc/howto/descriptor.rst#newcode380
Doc/howto/descriptor.rst:380: return self.f
Same as above.

http://bugs.python.org/review/23921/diff/14500/Doc/howto/functional.rst
File Doc/howto/functional.rst (left):

http://bugs.python.org/review/23921/diff/14500/Doc/howto/functional.rst#oldcode397
Doc/howto/functional.rst:397: if not (condition2):
On 2015/04/12 11:17:30, berkerpeksag wrote:
> if not condition2:

I think it is implied that condition2 is not a bare variable, but an
expression with operations that have lesser priority than "not". E.g.
"expr2 is None or expr2 < expr1". Parenthesis are required in such case.

Current code LGTM.

http://bugs.python.org/review/23921/diff/14500/Doc/howto/functional.rst#oldcode399
Doc/howto/functional.rst:399: ...
On 2015/04/12 11:17:30, berkerpeksag wrote:
> # ...

It is better to follow uniform style in all examples: "...  #". But an
empty comment is useless, so bare "..." looks good.

http://bugs.python.org/review/23921/diff/14500/Doc/howto/logging-cookbook.rst
File Doc/howto/logging-cookbook.rst (right):

http://bugs.python.org/review/23921/diff/14500/Doc/howto/logging-cookbook.rst#newcode713
Doc/howto/logging-cookbook.rst:713: if record is None:     # We send
this as a sentinel to tell the listener to quit.
This line already is too long, and additional spaces make it even
longer. This violates PEP 8. I would left this code (and other long
lines) as is. You can open new issue for long lines in examples.

http://bugs.python.org/review/23921/diff/14500/Doc/howto/regex.rst
File Doc/howto/regex.rst (right):

http://bugs.python.org/review/23921/diff/14500/Doc/howto/regex.rst#newcode1117
Doc/howto/regex.rst:1117: >>> p = re.compile( '(blue|white|red)' )
On 2015/04/12 19:55:06, jedwards wrote:
> On 2015/04/12 11:17:30, berkerpeksag wrote:
> > p = re.compile('(blue|white|red)')
> > 
> > Drop the trailing spaces please.
> 
> I agree, the reason for keeping it like this ( <- with spaces -> ) is
only
> because the author originally had a leading space before the arguments
and no
> trailing space after.
> 
> I tried to change as little as possible, so instead of removing the
leading
> space, I added a trailing space for balance.
> 
> But I agree that there should be neither.

I agree with Berker. We should remove spaces after "(" instead of adding
them before ")".

http://bugs.python.org/review/23921/diff/14500/Doc/library/html.parser.rst
File Doc/library/html.parser.rst (right):

http://bugs.python.org/review/23921/diff/14500/Doc/library/html.parser.rst#newcode294
Doc/library/html.parser.rst:294: 
Trailing spaces.

http://bugs.python.org/review/23921/diff/14500/Doc/library/subprocess.rst
File Doc/library/subprocess.rst (right):

http://bugs.python.org/review/23921/diff/14500/Doc/library/subprocess.rst#newcode942
Doc/library/subprocess.rst:942: # ==>
On 2015/04/12 19:55:06, jedwards wrote:
> On 2015/04/12 11:17:30, berkerpeksag wrote:
> > Perhaps ``# becomes`` or something like that would be better here.
> 
> The `# becomes` style is actually used earlier in the document:
> 
>
https://docs.python.org/3/library/subprocess.html#replacing-bin-sh-shell-backquote
> 
> I'm not sure why it changes part way through either.

Actually the first line even can not be Python 3 code (as the use of
`...` syntax above). May be these examples should be written as two
different code blocks with non-block message "becomes" or "==>" between
them.

Changes in this file can be non-trivial, so it would better to open a
separate issue for them and exclude this file from this patch.

http://bugs.python.org/review/23921/diff/14500/Doc/whatsnew/3.2.rst
File Doc/whatsnew/3.2.rst (right):

http://bugs.python.org/review/23921/diff/14500/Doc/whatsnew/3.2.rst#newcode215
Doc/whatsnew/3.2.rst:215: ...     conf = json.load(f)
I think this example (and other examples in this file) needs an empty
line after the block (i.e. the line with only the "..." prompt).

http://bugs.python.org/review/23921/diff/14500/Doc/whatsnew/3.2.rst#newcode1137
Doc/whatsnew/3.2.rst:1137: 
Trailing spaces.

http://bugs.python.org/review/23921/