nashif
commented
8 years ago by David Kinder:
The "next" and "previous" links at the bottom of the page are generated by Sphinx based on the .TOC directives used in the ReST files that hold the documentation sources. Sphinx expects chapters to be in separate ReST files organized by the .TOC directive into an hierarchical collection of chapters.
The left navigation is created from the heading hierarchy, "Getting Started Guide" is an H1, "Set Up the Development Environment" is an H2, "Development Environment Setup on Linux" is an H3, etc.
While the intuitive thought is that the "next" link at the bottom of the page will take you to the next heading in the left nav hierarchy (so you'd go from "Development Environment Setup on Windows" to "Checking Out the Source Code Anonymously") in fact, the "Checking out the Source Code Anonymously" section is not in a separate ReST file (it's contained within the getting_started.rst file). What's happening is the "next" for "Development Environment for Setup on Windows" is going to the next ReST file in the TOC hierarchy (which would be "Zepyr Kernel Primer").
If we really want the "next" and "previous" links to work intuitively, we need to keep the .TOC hierarchy and heading hierarchy consistent. We should not include any additional content with headings (that would add entries in the left nav area) after a nested .TOC directive. Alternatively, we just remove the "next" and "previous" links since it's causing this confusion.
Reported by Genaro Saucedo Tejada:
Getting started guide "next" link doesn't take you to "Checking Out the Source Code Anonymously" section
After "Development Environment Setup on Windows" it takes you to "Zephyr Kernel Primer"
(Imported from Jira ZEP-463)