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:

[leotrs]

Same issue - would be great if self behaved in the same way as other elements in the toctree.

[uberfastman]

So I have been wrestling with this issue myself as I wanted index.rst to display an external README.md being pulled from a parent directory with the .. include:: directive, and that README.md has various section headers that I wanted to show up as subsections within the toctree, but simply don't get rendered there when using the self keyword.

Per @arximboldi's workaround, you can reference index itself within the actual index.rst, which will then render the subsections in index.rst in the toctree as desired, but it will also have the unwanted side effect of duplicating any toctree files besides the index itself within the toctree (as noted in the comment on this reply to a stackoverflow post for this very issue here). It is worth noting that for me, using :maxdepth: 2 did not remove the recursive index entries from the other files added to index.rst, but the below improvement sorts that out.

Improvement to Workaround

After much tinkering, I realized that until self actually renders subsections (if ever), an alternative approach can be used to avoid the toctree file duplicates while still rendering subsections using the circular index keyword. Since sphinx supports the use of CUSTOM CSS, you can use the above approach with the index keyword, and then simply add a custom CSS file to your conf.py (add your custom css to the _static directory and make sure to include html_static_path = ["_static"] in conf.py), and within that custom CSS file you can target the duplicate elements in the toctree (both in the sidebar and the main content) like so:

/* necessary to remove the duplicated toctree entries created by referencing index in the sphinx index.rst */
.wy-menu-vertical > ul > li:nth-child(1),
.wy-menu-vertical > ul > li:nth-child(2),
.wy-nav-content .toctree-wrapper > ul > li:nth-child(1),
.wy-nav-content .toctree-wrapper > ul > li:nth-child(2) {
    display: none;
}

Of course this addition to the "solution" is still quite hacky, but it does result in a nice looking toctree with all subsections rendered and no duplicate toctree entries from other files in index.rst, so until there is a true solution implemented, hopefully this approach helps anyone trying to solve this issue.

[gilir-fcat]

Any news on this? It seems like a very common use case that is unfortunately not supported well currently (and the workaround didn't work for me for some reason).

[szarvas]

I don't think the main workaround of adding index to the toctree works anymore (Sphinx 8.2.3 at the time of writing this). It just emits a warning

WARNING: toctree contains reference to nonexisting document 'index' [toc.not_readable]

And the index document is entirely missing from the tree. Using self still works, but no subheadings.