Mailman 3 [issue23921] Standardize documentation whitespace, formatting - docs

April 12, 2015

      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-obfus...
[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 <report@bugs.python.org>
<http://bugs.python.org/issue23921>
_______________________________________

[issue23921] Standardize documentation whitespace, formatting

James Edwards

James Edwards

Serhiy Storchaka

Berker Peksag

R. David Murray

James Edwards

Serhiy Storchaka

James Edwards

James Edwards

Martin Panter

R. David Murray

R. David Murray

R. David Murray

Serhiy Storchaka

Georg Brandl

Serhiy Storchaka

Roundup Robot

Roundup Robot

Serhiy Storchaka

tags

participants (7)