classification
Title: Add a visual distinction to multiline versionchanged blocks
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.5
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: demian.brecht, docs@python, georg.brandl, r.david.murray
Priority: normal Keywords: patch

Created on 2015-03-25 15:22 by demian.brecht, last changed 2015-03-25 16:48 by demian.brecht. This issue is now closed.

Files
File name Uploaded Description Edit
versionchanged_indent.patch demian.brecht, 2015-03-25 15:22
Messages (5)
msg239261 - (view) Author: Demian Brecht (demian.brecht) * (Python triager) Date: 2015-03-25 15:22
This came up during #2211, where a multiline versionchanged entry was suggested. Currently, there is no visual distinction between any but the first line of the description and the rest of the body of the docs. The attached patch adds a consistent level of indentation (30px) to all but the first child. This change makes it much more obvious where the versionchanged block ends and the rest of the docs continue.
msg239263 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-03-25 15:34
Heh, you clearly know more about docutils/css than I do.

I don't think we want multiple blank delimited paragraphs under a versionchanged directive, though, from a style point of view.  A compact unordered list would be best.
msg239270 - (view) Author: Demian Brecht (demian.brecht) * (Python triager) Date: 2015-03-25 16:27
I noted in #2211 that nested lists are supported by Sphinx, so that solves that specific issue. Perhaps it /may/ still be useful to have this though in order to support multiple paragraphs for more detailed change descriptions when needed? That said, I'm not sure that's something that's necessarily even wanted as such messages are intended to be terse.
msg239273 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-03-25 16:42
Yes, exactly, they are supposed to be terse.  So I think we should reject this.
msg239274 - (view) Author: Demian Brecht (demian.brecht) * (Python triager) Date: 2015-03-25 16:48
Sounds good to me.
History
Date User Action Args
2015-03-25 16:48:06demian.brechtsetmessages: + msg239274
2015-03-25 16:42:01r.david.murraysetstatus: open -> closed
resolution: rejected
messages: + msg239273

stage: patch review -> resolved
2015-03-25 16:27:33demian.brechtsetmessages: + msg239270
2015-03-25 15:34:27r.david.murraysetnosy: + georg.brandl, r.david.murray
messages: + msg239263
2015-03-25 15:22:15demian.brechtcreate