classification
Title: devguide: buggy heading numbers
Type: behavior Stage:
Components: Devguide Versions:
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: chris.jerdonek, eric.araujo, ezio.melotti, georg.brandl, kushal.das, ncoghlan, pitrou, terry.reedy
Priority: normal Keywords: patch

Created on 2013-02-18 19:50 by pitrou, last changed 2014-04-28 22:26 by pitrou.

Files
File name Uploaded Description Edit
issue17227.patch kushal.das, 2013-02-22 05:47
Messages (10)
msg182338 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-02-18 19:50
If you look e.g. here:
http://docs.python.org/devguide/faq.html#communications

you'll see that all questions are numbered "25", while the upper headings are numbered "25.1", "25.2", etc.

Other places in the devguide seem fine, e.g. http://docs.python.org/devguide/stdlibchanges.html
msg182477 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2013-02-20 07:40
I noticed this before and wasn't able to fix it after trying a few things.  I wonder if this is a limitation or bug in Sphinx.  At the top, the FAQ page has--

:tocdepth: 2

Levels beyond 2 are getting numbered 25 (the number of the top level) instead of having their numbering suppressed (as I would expect it to).
msg182478 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-02-20 07:47
Georg, do you know how to fix this?
msg182480 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2013-02-20 07:56
> Levels beyond 2 are getting numbered 25 (the number of the top level) instead of having their numbering suppressed (as I would expect it to).

Actually, what I meant to say is that I would expect the "tocdepth" to affect only the level of the table of contents that is displayed (which it does), but not suppress or otherwise affect the numbering of the sections in the actual text.
msg182634 - (view) Author: Kushal Das (kushal.das) * (Python committer) Date: 2013-02-22 05:47
Adding a patch to fix this issue.
msg182641 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2013-02-22 05:55
> Adding a patch to fix this issue.

I had tried this, but doesn't this make the contents in the left side bar unwieldy (and perhaps also on the devguide index page) -- is that what we want?  I was under the assumption that the purpose of the tocdepth directive was to avoid that.
msg182644 - (view) Author: Kushal Das (kushal.das) * (Python committer) Date: 2013-02-22 06:07
>I had tried this, but doesn't this make the contents in the left side bar unwieldy (and perhaps also on the devguide index page) -- is that what we want?  I was under the assumption that the purpose of the tocdepth directive was to avoid that.

Yes, missed that issue. Trying to find any other solution if possible.
msg182653 - (view) Author: Kushal Das (kushal.das) * (Python committer) Date: 2013-02-22 07:12
I found that http://docs.python.org/devguide/stdlibchanges.html also has left side bar text with full index just like my patch does. For FAQ the problem is title texts are kind of long so they look bad.
msg217152 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-04-25 04:29
The only change is that '25' is now '28'.

A possible solution, without changing Sphinx, is to reduce the headers to a couple of words and put the question under the header, possibly in italics.

*Q. How do I do this difficult thing?*

A. Do 2 pushups, sleep 3 hours, drink water, and do it.

I am not sure how this would affect the linked index at the top that appears before 28.1 Communications.
msg217433 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2014-04-28 22:26
I agree with Chris, changing the tocdepth doesn't sound like the right solution. Is this a Sphinx bug? Georg, could you please take a look?
History
Date User Action Args
2014-04-28 22:26:49pitrousetmessages: + msg217433
2014-04-25 04:29:23terry.reedysetnosy: + terry.reedy
messages: + msg217152
2013-02-22 07:12:48kushal.dassetmessages: + msg182653
2013-02-22 06:07:10kushal.dassetmessages: + msg182644
2013-02-22 05:55:35chris.jerdoneksetmessages: + msg182641
2013-02-22 05:47:00kushal.dassetfiles: + issue17227.patch

nosy: + kushal.das
messages: + msg182634

keywords: + patch
2013-02-20 07:56:21chris.jerdoneksetmessages: + msg182480
2013-02-20 07:47:45pitrousetnosy: + georg.brandl
messages: + msg182478
2013-02-20 07:40:04chris.jerdoneksetmessages: + msg182477
2013-02-18 23:09:51chris.jerdoneksetnosy: + chris.jerdonek
2013-02-18 19:50:02pitroucreate