Repository navigation
devguide should have table of contents #60710
Description
| BPO | 16506 |
|---|---|
| Nosy | @brettcannon, @ncoghlan, @ezio-melotti, @merwok, @cjerdonek |
| Files |
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 2012-11-19.20:31:35.670>
created_at = <Date 2012-11-18.22:24:37.307>
labels = ['docs']
title = 'devguide should have table of contents'
updated_at = <Date 2012-11-19.20:31:35.669>
user = 'https://github.com/cjerdonek'bugs.python.org fields:
activity = <Date 2012-11-19.20:31:35.669>
actor = 'chris.jerdonek'
assignee = 'none'
closed = True
closed_date = <Date 2012-11-19.20:31:35.670>
closer = 'chris.jerdonek'
components = ['Devguide']
creation = <Date 2012-11-18.22:24:37.307>
creator = 'chris.jerdonek'
dependencies = []
files = ['28042']
hgrepos = []
issue_num = 16506
keywords = ['patch', 'needs review']
message_count = 6.0
messages = ['175926', '175941', '175942', '175957', '175958', '175966']
nosy_count = 6.0
nosy_names = ['brett.cannon', 'ncoghlan', 'ezio.melotti', 'eric.araujo', 'chris.jerdonek', 'python-dev']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue16506'
versions = []
Activity
cjerdonek commentedon Nov 18, 2012
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.
brettcannon commentedon Nov 19, 2012
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.
cjerdonek commentedon Nov 19, 2012
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).
cjerdonek commentedon Nov 19, 2012
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.
ncoghlan commentedon Nov 19, 2012
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.
python-dev commentedon Nov 19, 2012
New changeset 996b72dd1e31 by Chris Jerdonek in branch 'default':
Unhide and move table of contents to bottom of home page (issue bpo-16506).
http://hg.python.org/devguide/rev/996b72dd1e31