next/previous links in documentation skip some sections

[ggenellina]

BPO	7634
Nosy	@birkenfeld, @ezio-melotti

^{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/birkenfeld'
closed_at = <Date 2010-01-05.10:09:56.348>
created_at = <Date 2010-01-05.00:19:49.567>
labels = ['docs']
title = 'next/previous links in documentation skip some sections'
updated_at = <Date 2010-01-05.10:09:56.346>
user = 'https://bugs.python.org/ggenellina'

bugs.python.org fields:

activity = <Date 2010-01-05.10:09:56.346>
actor = 'georg.brandl'
assignee = 'georg.brandl'
closed = True
closed_date = <Date 2010-01-05.10:09:56.348>
closer = 'georg.brandl'
components = ['Documentation']
creation = <Date 2010-01-05.00:19:49.567>
creator = 'ggenellina'
dependencies = []
files = []
hgrepos = []
issue_num = 7634
keywords = []
message_count = 3.0
messages = ['97239', '97253', '97256']
nosy_count = 3.0
nosy_names = ['georg.brandl', 'ggenellina', 'ezio.melotti']
pr_nums = []
priority = 'normal'
resolution = 'works for me'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue7634'
versions = ['Python 2.6', 'Python 3.1', 'Python 2.7', 'Python 3.2']

[ggenellina]

The next/previous links in the documentation skip some sections. This happens both in HTML format and the CHM Windows help file.

e.g.: in the Library Reference, section "8.5 StringIO" [next] points to "8.7 textwrap", skipping section "8.6 cStringIO". And section "9.12 UserDict" [next] points to "9.15 Types", skipping sections 9.13 and 9.14 (UserList and UserString). Same with their reverse links: 9.15 [previous] points to 9.12.

It seems those links connect *files*, not *sections*, and such logic fails when a single file contains more than a section. From a user POV that's not the expected behavior: the next/previous links should navigate the complete document, regardless of its physical implementation (the actual .rst files).

(In that case this might be a Sphinx bug rather than a Python one)

[ezio-melotti]

I think the purpose of the 'next' and 'previous' is to move to the next/previous page (i.e. file) and not another section in the same page. If you read a page till the end and then you press 'next' you probably want to go to the next page, not to next section that is in the middle of the page that you just read.
I agree that sometimes it looks weird though, especially in the index.
The only thing that IMHO could be "fixed" is limiting the number of sections in a page to 1, otherwise I'd just close this as "won't fix".

[birkenfeld]

Ezio is right. The "next" links are meant to take you to the next logical file, and if one file contains multiple top-level sections, that is going to be several chapters away.