This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: devguide should have table of contents
Type: Stage: resolved
Components: Devguide Versions:
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: brett.cannon, chris.jerdonek, eric.araujo, ezio.melotti, ncoghlan, python-dev
Priority: normal Keywords: needs review, patch

Created on 2012-11-18 22:24 by chris.jerdonek, last changed 2022-04-11 14:57 by admin. This issue is now closed.

File name Uploaded Description Edit
issue-16506-1.patch chris.jerdonek, 2012-11-19 12:17
Messages (6)
msg175926 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-18 22:24
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.
msg175941 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2012-11-19 02:17
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.
msg175942 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-19 02:33
> The link does nothing because what is directly below the TOC link is the table of contents.

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:

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).
msg175957 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-19 12:17
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.
msg175958 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-11-19 12:45
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.
msg175966 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-11-19 20:29
New changeset 996b72dd1e31 by Chris Jerdonek in branch 'default':
Unhide and move table of contents to bottom of home page (issue #16506).
Date User Action Args
2022-04-11 14:57:38adminsetgithub: 60710
2012-11-19 20:31:35chris.jerdoneksetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2012-11-19 20:29:46python-devsetnosy: + python-dev
messages: + msg175966
2012-11-19 12:45:06ncoghlansetmessages: + msg175958
2012-11-19 12:17:07chris.jerdoneksetkeywords: + needs review, patch
files: + issue-16506-1.patch
messages: + msg175957

stage: patch review
2012-11-19 02:33:17chris.jerdoneksetmessages: + msg175942
2012-11-19 02:17:37brett.cannonsetnosy: + brett.cannon
messages: + msg175941
2012-11-18 22:24:37chris.jerdonekcreate