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.
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
devguide should have table of contents #60710
Comments
Currently, the devguide does not have a table of contents. For example, clicking the "Table of Contents" link in the left column does nothing. My feeling is that a proper table of contents will make it easier to understand how the devguide is organized at a high level and to track what parts one has read and not read. It is currently not so easy to do this. |
The link does nothing because what is directly below the TOC link is the table of contents. There was originally a TOC but it was removed when it pushed too much of the quick start section off of the screen at initial load. You also don't want a large TOC as that can seem daunting to a newbie. |
Yes, that's the impression one gets when the link doesn't work. But the links below are just the sections for the current page rather than the table of contents for the devguide. Compare, for example, the left column here: http://docs.python.org/dev/library/argparse.html The table of contents for the devguide can go on a separate page like it's done for the Python documentation. We can decide what level of sectioning to display (assuming Sphinx lets you configure that). Personally, I think I would prefer a shallow TOC (i.e. one or two levels). |
Attaching patch. Out-of-the-box at least, Sphinx seems to have the constraint that the "home page" (what the link in the upper-left corner points to) needs to be the same as the table of contents (what the "table of contents" link in the left column points to). Retaining the same home page seems to be the most important, so for now at least, I'm proposing putting the table of contents at the bottom of the home page (with the home page itself not part of the contents). I also re-did the header formatting for a few pages to make the nesting levels match the page list. |
Sounds good to me - I was looking for a link to the maintainer list the other day, and there doesn't appear to be one at the moment. Having a reasonably complete ToC/site map deals with that kind of problem, and putting it at the bottom helps avoid overwhelming newcomers. |
New changeset 996b72dd1e31 by Chris Jerdonek in branch 'default': |
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:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: