Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Nest class/methods directives in documentation #57110

Closed
merwok opened this issue Sep 5, 2011 · 3 comments
Closed

Nest class/methods directives in documentation #57110

merwok opened this issue Sep 5, 2011 · 3 comments
Labels
docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@merwok
Copy link
Member

merwok commented Sep 5, 2011

BPO 12901
Nosy @birkenfeld, @benjaminp, @ezio-melotti, @merwok
Files
  • doc-nest-methods-3.2.diff
    		•

    Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = None
closed_at = <Date 2014-03-15.09:13:41.371>
created_at = <Date 2011-09-05.16:45:19.305>
labels = ['type-feature', 'docs']
title = 'Nest class/methods directives in documentation'
updated_at = <Date 2014-03-15.09:13:41.371>
user = 'https://github.com/merwok'

    bugs.python.org fields:

    activity = <Date 2014-03-15.09:13:41.371>
actor = 'georg.brandl'
assignee = 'docs@python'
closed = True
closed_date = <Date 2014-03-15.09:13:41.371>
closer = 'georg.brandl'
components = ['Documentation']
creation = <Date 2011-09-05.16:45:19.305>
creator = 'eric.araujo'
dependencies = []
files = ['23102']
hgrepos = []
issue_num = 12901
keywords = ['patch']
message_count = 3.0
messages = ['143552', '213383', '213421']
nosy_count = 5.0
nosy_names = ['georg.brandl', 'benjamin.peterson', 'ezio.melotti', 'eric.araujo', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = 'works for me'
stage = None
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue12901'
versions = ['Python 2.7', 'Python 3.3', 'Python 3.4']
    @merwok
    Copy link
    Member Author

    merwok commented Sep 5, 2011

    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?

    @merwok merwok added the docs Documentation in the Doc dir label Sep 5, 2011
    @ezio-melotti ezio-melotti added the type-feature A feature request or enhancement label Jan 11, 2013
    @merwok
    Copy link
    Member Author

    merwok commented Mar 13, 2014

    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.

    @birkenfeld
    Copy link
    Member

    Agreed.

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    docs Documentation in the Doc dir type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    3 participants
    @birkenfeld @merwok @ezio-melotti