[docs] [issue23921] Standardize documentation whitespace, formatting

James Edwards report at bugs.python.org
Tue Apr 14 03:40:25 CEST 2015


James Edwards added the comment:

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.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue23921>
_______________________________________


More information about the docs mailing list