Using self in toctree doesn't include sub-sections

Question

I would like my toctree in sphinx to include the main (index.rst) page. The documents suggest that including 'self' will do this, but as others have noted on stackoverflow this only includes the title of the main page, so that if depth > 1 the behavior for the main page is different from the linked pages.

I've also seen the contents directive suggested for this issue, for me this just creates a separate local list of contents and doesn't help with the toctree. I'm really looking for a solution that produces a consistent behavior in the toctree. Is there one?

Answer 1

Including the literal self just adds the title of the current document as you mentioned. However, including the title of the current document actually adds it to the tree. For example,

.. toctree::
    :maxdepth: 2

    index

will produce the result you want. I am not sure why this is not explicitly listed in the documentation somewhere.