classification
Title: Use PEP8 in documentation examples
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, ezio.melotti, inada.naoki, martin.panter, mdk, rhettinger
Priority: normal Keywords:

Created on 2016-01-06 22:06 by mdk, last changed 2016-01-10 15:59 by ezio.melotti. This issue is now closed.

Messages (8)
msg257649 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2016-01-06 22:06
Hi,

Shouldn't Python use PEP8 in its examples in the documentation ? I found a lot of missing spaces around binary operators, and things like "setup (name = 'PackageName'," (found in the Distributing section, but that's just a single example) which hurt my eyes and will probably teach bad practices to newcomers reading it.

If everybody agree documentation examples should be PEP8 compliant, I'll can gladly provide some patches.

I also found http://bugs.python.org/issue23921 which is probably not merged as it's still open, and the patch don't fix my example, so there is probably some problems left.
msg257661 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-01-06 23:39
In general I agree with fixing style problems in the documentation, especially if you supply patches :)
msg257674 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-01-07 06:46
> I found a lot of missing spaces around binary operators

Please don't make trivial changes like this.
msg257675 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-01-07 07:06
If it is fixing stuff like “lambda x: x +1” (from Issue 23921), I am in favour. But if the code example is self-consistent and uses a reasonable style, it should not be changed. Julien, perhaps you should give an example to clarify.
msg257676 - (view) Author: Inada Naoki (inada.naoki) * (Python committer) Date: 2016-01-07 07:16
No spaces around binary operator is OK in PEP8.
See http://bugs.python.org/issue11425
msg257838 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2016-01-09 14:38
Without a list of places that don't follow the PEP8, I'm going to close this.
msg257841 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2016-01-09 16:02
I opened this ticket mainly to know the opinions on those modifications, I'll slowly review what I see, and provide little patches from time to time, only when the PEP8 infringement look obvious.

I think the most obvious PEP8 infringement ARE to be fixed, typically in the tutorial: The documentation is where people learn, let's teach them the right thing to do :-)

Thanks to naoki I just learnt that no spaces around binary operators are OK  when it enhance the readability (https://www.python.org/dev/peps/pep-0008/#other-recommendations) like 2*2 + 3*2.

I close this ticket, I'll just mention if I propose a patch in a new one.

Bests.
msg257918 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2016-01-10 15:59
> I'll slowly review what I see, and provide little patches from
> time to time, only when the PEP8 infringement look obvious.

Sounds good to me.  If you are not sure you can ask on IRC (#python-dev on freenode) or the core-mentorship mailing list.
History
Date User Action Args
2016-01-10 15:59:00ezio.melottisetmessages: + msg257918
2016-01-09 22:05:09berker.peksagsetstage: needs patch -> resolved
2016-01-09 16:02:58mdksetstatus: pending -> closed

messages: + msg257841
2016-01-09 14:38:20ezio.melottisetstatus: open -> pending
resolution: not a bug
messages: + msg257838
2016-01-08 17:34:27ezio.melottisetnosy: + ezio.melotti

versions: + Python 3.6
2016-01-07 07:16:09inada.naokisetnosy: + inada.naoki
messages: + msg257676
2016-01-07 07:06:16martin.pantersetmessages: + msg257675
2016-01-07 06:46:45rhettingersetnosy: + rhettinger
messages: + msg257674
2016-01-06 23:39:46martin.pantersetnosy: + martin.panter

messages: + msg257661
stage: needs patch
2016-01-06 22:06:04mdkcreate