Sphinx: Tree doesn't include subsections for `self` in toctree

[AndreiPashkin]

Here is the example:
https://raw.githubusercontent.com/dateutil/dateutil/master/docs/index.rst

And the result is:
https://dateutil.readthedocs.org/en/latest/

Notice - subsections in a tree side-bar are absent.

Similar issues on SO:
http://stackoverflow.com/questions/27338257/using-self-in-sphinx-toctree-doesnt-include-sub-sections
http://stackoverflow.com/questions/20648956/adding-subsections-of-self-in-the-table-of-contents

[tk0miya]

Since the appearance of self in 38e766c2, it always only includes the title of the current file. not whole of ToC of the file.

@birkenfeld What is the purpose of the keyword? It seems not enough to use as "sitemap". So I don't know how to use this feature.
Could you tell me your idea?

[birkenfeld]

TBH, I don't know anymore :)

[lukasgraf]

I stumbled across the same issue - including self in the toctree only inserts a single link to the same document (irrespective of maxdepth), so I don't see how this could be used to generate a sitemap or a document-local ToC (which is what I'm after).

Using the plain reStructuredText .. contents:: directive is _somewhat_ of an alternative, but doesn't have the same features as Sphinx's toctree (e.g. no numbering support).

[arximboldi]

Workaround: add the index page explicitly to the TOC. E.g. If your master document is called index, do something like:

.. toctree::
    :maxdepth: 2

    index
    tutorial
    ...

Note that without :maxdepth: the TOC entries itself are shown inside the TOC itself recursively once. Also, there are warnings on the console:

/home/raskolnikov/dev/immer/doc/index.md:: WARNING: circular toctree references detected, ignoring: index <- index

[arximboldi]

Oh no! My workaround has one mayor drawback: in the sidebar TOC, when you are in a page other than the index, the Index page entry itself is "opened" and the part of the document where the toc is included is highlighted. Example: