Divide Sphinx TOC into subsections with subheadings

Question

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?

Answer 1

One option is to do it like this:

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

    doc1
    doc2
    doc3

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

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

    doc4
    doc5
    doc6