Divide Sphinx TOC into subsections with subheadings

python-sphinx, restructuredtext, toctree

Solution

One option is to do it like this:

.. toctree::
    :maxdepth: 2
    :numbered:

    doc1
    doc2
    doc3

Subheading
-----------

.. toctree::
    :maxdepth: 2
    :numbered:

    doc4
    doc5
    doc6

Problem

I have a Sphinx master document which includes child documents as follows: ``` .. toctree:: :maxdepth: 2 :numbered: doc1 doc2 doc3 doc4 doc5 doc6 ``` I would like to divide the TOC into parts or subsections, so that it renders along the lines of: ``` Part 1: Title of Part 1 <doc1 TOC> <doc2 TOC> Part 2: Title of Part 2 <doc3 TOC> <doc4 TOC> Part 3: Title of Part 3 <doc5 TOC> <doc6 TOC> ``` My current approach is to create pseudo-child documents, that list the actual documents in their TOC, for example, "part1.rst" would have: ``` .. toctree:: :maxdepth: 2 :numbered: doc1 doc2 ``` and then in the master document: ``` .. toctree:: :maxdepth: 3 :numbered: part1 part2 part3 ``` The problem with this is that when clicking the link for "part1", you are taken to a page with no real content ("part1.rst"). Is there any other approach? Alternatively, is there a way to suppress the entry for "part1.rst" from generating a page link?

Original source