devguide: buggy heading numbers

[pitrou]

BPO	17227
Nosy	@brettcannon, @birkenfeld, @terryjreedy, @ncoghlan, @pitrou, @ezio-melotti, @merwok, @cjerdonek, @berkerpeksag, @kushaldas, @willingc
Files	issue17227.patch iss17227.patch

^{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 = 'https://github.com/willingc'
closed_at = <Date 2016-07-22.19:51:32.461>
created_at = <Date 2013-02-18.19:50:02.314>
labels = ['type-bug', 'docs']
title = 'devguide: buggy heading numbers'
updated_at = <Date 2016-07-22.19:51:32.459>
user = 'https://github.com/pitrou'

bugs.python.org fields:

activity = <Date 2016-07-22.19:51:32.459>
actor = 'brett.cannon'
assignee = 'willingc'
closed = True
closed_date = <Date 2016-07-22.19:51:32.461>
closer = 'brett.cannon'
components = ['Devguide']
creation = <Date 2013-02-18.19:50:02.314>
creator = 'pitrou'
dependencies = []
files = ['29155', '39111']
hgrepos = []
issue_num = 17227
keywords = ['patch']
message_count = 14.0
messages = ['182338', '182477', '182478', '182480', '182634', '182641', '182644', '182653', '217152', '217433', '241463', '241470', '241526', '271019']
nosy_count = 11.0
nosy_names = ['brett.cannon', 'georg.brandl', 'terry.reedy', 'ncoghlan', 'pitrou', 'ezio.melotti', 'eric.araujo', 'chris.jerdonek', 'berker.peksag', 'kushal.das', 'willingc']
pr_nums = []
priority = 'normal'
resolution = 'out of date'
stage = 'patch review'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue17227'
versions = []

[pitrou]

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

[cjerdonek]

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).

[pitrou]

Georg, do you know how to fix this?

[cjerdonek]

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.

[kushaldas]

Adding a patch to fix this issue.

[cjerdonek]

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.

[kushaldas]

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.

[kushaldas]

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.

[terryjreedy]

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.

[pitrou]

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?

[willingc]

Correct Python Developer FAQ Section 28 to match the style of Section 27.

Section numbers should now flow correctly in Sphinx. A section contents is displayed at the top of the section page for the user's convenience (especially since the FAQ questions have long titles).

[berkerpeksag]

Thanks! The patch doesn't address msg182641 and I think this is a Sphinx bug(or perhaps a feature request?). tocdepth should not change the heading numbers. I couldn't find any similar report on the Sphinx issue tracker. So I suggest opening an issue there and closing this one as "third party".

[willingc]

Berker, Thanks for the patch review. I'm going to work with the folks at Sphinx project this week to see if the headings are fixed in a newer Sphinx version. If so, I will make the change here. If not, I will follow your recommendation to close and create an issue on the Sphinx issue tracker.

[brettcannon]

Moved to python/devguide#11