This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author jedwards
Recipients berker.peksag, docs@python, jedwards, r.david.murray, serhiy.storchaka
Date 2015-04-14.01:40:24
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1428975625.18.0.334557730599.issue23921@psf.upfronthosting.co.za>
In-reply-to
Content
Thanks Berker, I responded to most of your comments in rietveld.

A few of your comments suggested "we should get rid of X", and while I can't say I disagree, I really tried to limit the scope of the changes to whitespace and formatting.

As far as the script goes, it still requires significant human interaction.

Of the 1983 code snippets it extracts[1], 346 still raise warnings and require human verification.  The majority of these snippets aren't actually intended to be Python code.  Some of the snippets are C code, others are optparse/argparse command line examples, configparser config files, or just sections where the author wanted to use a literal block in the documentation.[2]

Of course, when the script triggers on one of these blocks, I ignore it.

Eventually, my goal was to have the script also verify interactive code blocks, much like doctest, but I thought a good intermediary step was to unify the whitespace.

As for the value, I understand the concern one might have before embarking on the process of standardizing the whitespace and formatting -- but given that it's mostly done and comes neatly packaged in a patch, I'm not sure I understand any remaining concerns.  In other words, if it's not something you would spend time on personally, because you have better ways to contribute/ spend your time, I absolutely understand that.  But given that the majority of the leg work is done by the patch, I hope you'll consider merging the changes.

In general the goal was to make the snippets, especially in the tutorial-type sections consistent, to allow the reader to become comfortable with the language instead of being distracted by varied formatting and to facilitate readability.  I hope this explains the motivation behind the effort.

[1] Some files were ignored from future runs after the snippets were validated, because they contained too many false positives, e.g. ctypes.rst.  So this count doesn't reflect the blocks in those ignored files.

[2] I wonder if explicitly indicating which rst literal blocks are intended to be python code would be of some benefit.  For example, adding such a tag could trigger the automatic formatting checks and, for interactive blocks, run the automatic doctest-type verification I was envisioning.  I may think more about the feasibility of this and bring it to python-ideas/python-dev.
History
Date User Action Args
2015-04-14 01:40:25jedwardssetrecipients: + jedwards, r.david.murray, docs@python, berker.peksag, serhiy.storchaka
2015-04-14 01:40:25jedwardssetmessageid: <1428975625.18.0.334557730599.issue23921@psf.upfronthosting.co.za>
2015-04-14 01:40:25jedwardslinkissue23921 messages
2015-04-14 01:40:24jedwardscreate