[issue12901] Nest class/methods directives in documentation

New submission from Éric Araujo <merwok@netwok.org>: 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? ---------- assignee: docs@python components: Documentation messages: 143552 nosy: benjamin.peterson, docs@python, eric.araujo, georg.brandl priority: normal severity: normal status: open title: Nest class/methods directives in documentation versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12901> _______________________________________

Changes by Éric Araujo <merwok@netwok.org>: ---------- keywords: +patch Added file: http://bugs.python.org/file23102/doc-nest-methods-3.2.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12901> _______________________________________

Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti type: -> enhancement versions: +Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12901> _______________________________________

Éric Araujo added the comment: 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. ---------- status: open -> pending versions: -Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12901> _______________________________________

Georg Brandl added the comment: Agreed. ---------- status: pending -> open _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12901> _______________________________________

Changes by Georg Brandl <georg@python.org>: ---------- resolution: -> works for me status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12901> _______________________________________
participants (3)
-
Ezio Melotti
-
Georg Brandl
-
Éric Araujo