I need a way to escape from Sphinx’s limitation that HTML output contains one and only one page per level-1 heading. For the sake of readability, some of my document’s content must be divided into pages at a lower heading level.
I’m considering whether I can do this by manipulating the table of contents in the left sidebar, as follows.
Suppose I have a document with this structure:
Little section
A subsection
Another subsection
Big section
Level 2 in a big section
Another level 2 in a big section
Another little section
Normally the document would have three pages beginning with the headings “Little section,” “Big section,” and “Another little section.” But I want two additional pages, beginning with the headings “Level 2 in a big section” and “Level 2 in another big section.” I would do this as follows.
Put each level-2 section in a separate reST file, which makes its initial heading a level-1 heading from Sphinx’s point of view.
Add the :orphan: option to each “level 2” reST file so that it doesn’t appear in the sidebar TOC automatically.
Manually add level-2 entries to the sidebar TOC under “Big section” which have the text “Level 2 in a big section” and “Another level 2 in a big section,” and link to the orphaned “level 2” files.
I’m asking whether this is possible because I saw the following statement on sphinx-doc.org Directives page. I have put the relevant part in italics:
You can also give a “hidden” option to the [toctree] directive, like this:
.. toctree:: :hidden: doc_1 doc_2This will still notify Sphinx of the document hierarchy, but not insert links into the document at the location of the directive – this makes sense if you intend to insert these links yourself, in a different style, or in the HTML sidebar.
This appears to say: Yes, what I propose is possible. But I can’t find a clue to how it’s done. Can anyone provide insight?