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)

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

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.

nosy: + ezio.melotti
messages: + msg97253