classification
Title: devguide should mention rules about "paragraph reflow" in the documentation
Type: behavior Stage: needs patch
Components: Devguide, Documentation Versions:
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: docs@python Nosy List: akira, brett.cannon, docs@python, ezio.melotti, georg.brandl, martin.panter, r.david.murray, terry.reedy, willingc
Priority: normal Keywords: easy

Created on 2015-01-25 21:06 by akira, last changed 2016-07-22 19:54 by brett.cannon. This issue is now closed.

Messages (7)
msg234692 - (view) Author: Akira Li (akira) * Date: 2015-01-25 21:06
It is suggested in https://bugs.python.org/issue23251
that only a core Python developer may reflow paragraphs
while submitting patches for the Python documentation.

It should be codified in devguide: I haven't found the
word *reflow* in it.
msg234695 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-01-25 21:30
That wording is a bit strong :).

On that issue I requested a patch without the reflow, because I prefer that.  Personally, I think it is in fact worth noting in the devguide that it is better for doc patches to not reflow paragraphs so that it is easier to see just the changed text in the patch file and in the 'hg diff' output.

However, since reitveld can handle reflowed paragraphs, other developers my not agree with me on this.
msg235085 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2015-01-31 07:37
For normal paragraphs, long and short lines make no difference to Sphinx and subsequent output.  I would like to know and have documented when (how uneven the lines) a reflow is otherwise considered necessary.
msg235086 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2015-01-31 07:48
For patches to be reviewed (whether submitted by a core developer or not), there should be as little spurious changes as possible.  In the final commit, it's ok, but not mandatory, to reflow the paragraphs.
msg237028 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2015-03-02 08:18
Agreed with what Georg said and I think the devguide can be update accordingly.
msg241090 - (view) Author: Carol Willing (willingc) * (Python committer) Date: 2015-04-15 08:44
https://bugs.python.org/issue18041 also provides related insights. Ideally, a patch for this issue should address and close both issues.
msg271022 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2016-07-22 19:54
Moved to https://github.com/python/devguide/issues/12
History
Date User Action Args
2016-07-22 19:54:44brett.cannonsetstatus: open -> closed

nosy: + brett.cannon
messages: + msg271022

resolution: out of date
2015-04-15 08:44:57willingcsetnosy: + willingc
messages: + msg241090
2015-03-02 08:18:40ezio.melottisetassignee: docs@python
components: + Documentation

keywords: + easy
nosy: + docs@python
messages: + msg237028
stage: needs patch
2015-01-31 07:48:51georg.brandlsetmessages: + msg235086
2015-01-31 07:37:11terry.reedysetnosy: + terry.reedy, georg.brandl
messages: + msg235085
2015-01-25 21:48:38martin.pantersetnosy: + martin.panter
2015-01-25 21:30:32r.david.murraysetnosy: + r.david.murray
messages: + msg234695
2015-01-25 21:06:33akiracreate