classification
Title: Nest class/methods directives in documentation
Type: enhancement Stage:
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: works for me
Dependencies: Superseder:
Assigned To: docs@python Nosy List: benjamin.peterson, docs@python, eric.araujo, ezio.melotti, georg.brandl
Priority: normal Keywords: patch

Created on 2011-09-05 16:45 by eric.araujo, last changed 2014-03-15 09:13 by georg.brandl. This issue is now closed.

Files
File name Uploaded Description Edit
doc-nest-methods-3.2.diff eric.araujo, 2011-09-05 16:45
Messages (3)
msg143552 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-09-05 16:45
I picked up a few files in Doc/library and updated their markup to use directives nesting.  The attached patch is the result; it’s a lot of changes for small benefit.  If we think it’s a good change anyway, I have two questions

- Do you think it would be a good idea to have the -checkins emails ignore whitespace changes in some cases?  (I’m thinking a magic string in the commit message)

- A number of files have a class directive near the top of the file, in the list of all public names, and a later section “XX objects” with the methods and attributes.  When this is changed to nested class/methods directives, sometimes the first class directive gets a noindex flag, but I think it should jsut be removed: the index in the sidebar is enough to let people jump to the doc.  Do you agree?
msg213383 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-03-13 10:34
I’m inclined to reject this patch: it doesn’t apply cleanly anymore, it does not cover all modules, and basically it’s markup changes without benefits for end users.

Our doc can recommend nesting class and methods directives for new doc, and existing doc may or may not be changed when someone improves the contents.
msg213421 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2014-03-13 17:31
Agreed.
History
Date User Action Args
2014-03-15 09:13:41georg.brandlsetstatus: open -> closed
resolution: works for me
2014-03-13 17:31:09georg.brandlsetstatus: pending -> open

messages: + msg213421
2014-03-13 10:34:06eric.araujosetstatus: open -> pending

messages: + msg213383
versions: - Python 3.2
2013-01-11 05:07:28ezio.melottisetnosy: + ezio.melotti

type: enhancement
versions: + Python 3.4
2011-09-05 16:45:39eric.araujosetfiles: + doc-nest-methods-3.2.diff
keywords: + patch
2011-09-05 16:45:19eric.araujocreate