[docs] Standardize documentation whitespace, formatting (issue 23921)
jheiv at jheiv.com
jheiv at jheiv.com
Sun Apr 12 19:55:06 CEST 2015
Reviewers: berkerpeksag,
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 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.
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 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.
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 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.
http://bugs.python.org/review/23921/diff/14500/Doc/reference/simple_stmts.rst
File Doc/reference/simple_stmts.rst (right):
http://bugs.python.org/review/23921/diff/14500/Doc/reference/simple_stmts.rst#newcode334
Doc/reference/simple_stmts.rst:334: if not expression: raise
AssertionError
On 2015/04/12 11:17:30, berkerpeksag wrote:
> if not expression:
> raise AssertionError
Yes, this would be the most compliant, and I can change this.
Because of the many lines of code in the docs that contain what I called
"trival blocks" in-line with conditions, I had to start conditionally
ignoring them.
if <cond>: <trivial block>
Ended up getting ignored, provided that <trivial block> was exactly
"pass", "continue", "break", or (less trivially) started with "print" or
"raise".
Please review this at http://bugs.python.org/review/23921/
Affected files:
Doc/distutils/apiref.rst
Doc/faq/design.rst
Doc/faq/library.rst
Doc/faq/programming.rst
Doc/howto/curses.rst
Doc/howto/descriptor.rst
Doc/howto/functional.rst
Doc/howto/logging-cookbook.rst
Doc/howto/logging.rst
Doc/howto/regex.rst
Doc/howto/unicode.rst
Doc/howto/urllib2.rst
Doc/howto/webservers.rst
Doc/library/abc.rst
Doc/library/argparse.rst
Doc/library/asynchat.rst
Doc/library/asyncio-sync.rst
Doc/library/asyncore.rst
Doc/library/audioop.rst
Doc/library/collections.abc.rst
Doc/library/collections.rst
Doc/library/concurrent.futures.rst
Doc/library/configparser.rst
Doc/library/contextlib.rst
Doc/library/crypt.rst
Doc/library/ctypes.rst
Doc/library/email.headerregistry.rst
Doc/library/getopt.rst
Doc/library/html.parser.rst
Doc/library/http.client.rst
Doc/library/inspect.rst
Doc/library/ipaddress.rst
Doc/library/locale.rst
Doc/library/mailcap.rst
Doc/library/mmap.rst
Doc/library/multiprocessing.rst
Doc/library/optparse.rst
Doc/library/re.rst
Doc/library/shelve.rst
Doc/library/ssl.rst
Doc/library/string.rst
Doc/library/subprocess.rst
Doc/library/threading.rst
Doc/library/tkinter.rst
Doc/library/tokenize.rst
Doc/library/types.rst
Doc/library/unittest.rst
Doc/library/urllib.request.rst
Doc/library/wsgiref.rst
Doc/library/xml.dom.minidom.rst
Doc/library/xml.etree.elementtree.rst
Doc/library/xmlrpc.client.rst
Doc/reference/datamodel.rst
Doc/reference/expressions.rst
Doc/reference/simple_stmts.rst
Doc/tutorial/appendix.rst
Doc/tutorial/classes.rst
Doc/tutorial/controlflow.rst
Doc/tutorial/errors.rst
Doc/tutorial/inputoutput.rst
Doc/tutorial/introduction.rst
Doc/tutorial/modules.rst
Doc/tutorial/stdlib.rst
Doc/tutorial/stdlib2.rst
Doc/whatsnew/3.2.rst
Doc/whatsnew/3.3.rst
Doc/whatsnew/3.4.rst
More information about the docs
mailing list