New submission from James Edwards:
I realize this is a huge patch, I'd be happy to split it to multiple little
patches (one per file, one per documentation directory, etc.) to make things
easier. Just let me know.
The patch attempts to do a few things (with exceptions, as noted below):
1. Standardize leading whitespace in block bodies (4 spaces per level)
2. Enforce >= 2 spaces between code and inline comment
3. In interactive interpreter snippets, ensures lines meant to be entered
are preceded by '>>> ' or '... '
4. Inline whitespace standardization (following a liberal / lenient
(not strict) PEP-8 testing)
Scanning the documentation, extracting the code snippets, and testing them for
PEP-8 compliance was done with a script, but all adjustments were done by hand.
This means that there remain some code that fails the lenient PEP-8 checks that
I used. For example, code at [1] ("How to write obfuscated one liners")
obviously threw errors, but because of the context of the snippet and the use
it
serves in the documentation, it was left it unchanged.
Similarly, there are (intentionally) poorly formatted snippets in [2] ("Lexical
Analysis") that were also left unchanged.
Since these changes were applied by hand, I was able to ignore situations where
things that would normally raise warnings. I erred on the side of leaving the
documentation examples unchanged, and strived to make only innocuous changes.
I made no attempt to change the functionality or semantics of any of the
snippets. The only changes I made were "harmless" formatting. None of the
changes will affect the function or output of the snippets.
What the changes do, however, is give a consistency to the documentation that
will allow readers to become more comfortable with the structure of the language
and improve readability.
[1]
https://docs.python.org/3/faq/programming.html#is-it-possible-to-write-obfuscated-one-liners-in-python
[2] https://docs.python.org/3/reference/lexical_analysis.html#indentation
[3] http://pep8.readthedocs.org/en/latest/intro.html
In addition to the checks that are ignored by default by the pep8[3] module for
not being unanimously accepted:
E121 # continuation line under-indented for hanging indent
E123 # closing bracket does not match indentation of opening bracket’s
line
E126 # continuation line over-indented for hanging indent
E133 # closing bracket is missing indentation
E226 # missing whitespace around arithmetic operator
E241 # multiple spaces after ‘,’
E242 # tab after ‘,’
E704 # multiple statements on one line (def)
The following checks were "globally" ignored in my script, though many others
were conditionally ignored by the script or by myself.
ignore.append('W292') # no newline at end of file
ignore.append('E302') # expected 2 blank lines, found 0
ignore.append('E401') # multiple imports on one line
ignore.append('W391') # blank line at end of file
ignore.append('E231') # missing whitespace after ','
ignore.append('E114') # indentation is not multiple of four (comment)
ignore.append('E116') # unexpected indentation (comment)
While the patch diffstat is:
67 files changed, 450 insertions(+), 412 deletions(-)
Ignoring all whitespace changes, the diffstat is only:
10 files changed, 118 insertions(+), 114 deletions(-)
The majority of these remaining changes fix the inconsistency of interactive
interpreter snippets, where, within the same snippet, some lines have '>>> '
while others are missing it, or the '... ' continuation prompt.
Let me know if you need anything from me (such as splitting this patch up) to
help get it merged. Thanks.
----------
assignee: docs@python
components: Documentation
files: docsdiff.diff
keywords: patch
messages: 240540
nosy: docs@python, jedwards
priority: normal
severity: normal
status: open
title: Standardize documentation whitespace, formatting
type: enhancement
Added file: http://bugs.python.org/file38903/docsdiff.diff
_______________________________________
Python tracker <rep...@bugs.python.org>
<http://bugs.python.org/issue23921>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
