-
Notifications
You must be signed in to change notification settings - Fork 2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Tree doesn't include subsections for self
in toctree
#2103
Comments
Since the appearance of @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. |
TBH, I don't know anymore :) |
I stumbled across the same issue - including Using the plain reStructuredText |
Workaround: add the index page explicitly to the TOC. E.g. If your master document is called
Note that without :maxdepth: the TOC entries itself are shown inside the TOC itself recursively once. Also, there are warnings on the console:
|
This is a workaround for the contents.rst file, which we have to use even for a single file, e.g. sphinx-doc/sphinx#2103 This will be automatically solved by version 3 as we use multiple pages then.
This is a workaround for the contents.rst file, which we have to use even for a single file, e.g. sphinx-doc/sphinx#2103 This will be automatically solved by version 3 as we use multiple pages then.
This is a workaround for the contents.rst file, which we have to use even for a single file, e.g. sphinx-doc/sphinx#2103 This will be automatically solved by version 3 as we use multiple pages then.
I wanted to have all geocoders listed in the sidebar toctree, because viewing docs for a specific geocoder is quite a common use-case. Apparently without introducing level 3 headers that's impossible [1]. sphinx-rtd-theme for some reason cannot render third level of headings correctly in the sidebar without a `toctree` present in the doc: they appear at the second level along with the other level two headers. Hence the need to have `toctree` in the doc. It could've been hidden, but I figured it might be helpful to have it visible in the doc. Will see how it goes. The toctree references the same document, which causes a warning regarding a circular reference, yet it's the only option I could find to have the third level of headings be correctly rendered in the sidebar [2]. [1]: https://stackoverflow.com/a/18002745 [2]: sphinx-doc/sphinx#2103
The "contents" page contains the global ToC tree, but actually it is not needed as a separate page. Unfortunately, there is no easy way to avoid rendering of this page in Sphinx. As a workaround, this page is skipped during deployment. But Sphinx still includes it in the global ToC and generates a "prev" link to it in the "index" page. Alternative solution could be removing the "contents" page and putting global ToC into the "index" page. But there is a problem with self referencing in Sphinx: sphinx-doc/sphinx#2103 So, as a workaround, now the layout is altered to explicitly avoid "prev" link from the "index" page.
Same issue - would be great if |
So I have been wrestling with this issue myself as I wanted Per @arximboldi's workaround, you can reference Improvement to WorkaroundAfter much tinkering, I realized that until /* 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 |
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). |
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
The text was updated successfully, but these errors were encountered: