Prevent Sub-section Nesting In Python Sphinx When Using Toctree

I'm running into a problem in structuring my Sphinx users guide. I would like to form a chapter by having a main landing page (index.rst) that contains the chapter heading and an o

Solution 1:

I had exactly the same problem, and couldn't find a nice solution. The only options seemed to be either remove the sub-heading ('Overview' in the example above) or mark it up as a rubric, e.g.

.. rubric:: Overview

which means it doesn't get included in the TOC. It should be possible to apply styling to the rubric so it looks like a sub-heading, but doing it this way feels like a bit of a hack.

Solution 2:

For the latex pdf generator, you could sneek in overview as a same-level heading like this:

.. raw:: latex

    \chapter{Overview}

Solution 3:

There is a good guide on how to Create a custom landing page in Sphinx.

The idea is that you create a separate page for the toc (contents.rst), and make your landing page index.rst (or index.html). Then you change

master_doc = 'contents'

in conf.py (it was index by default).