Page TOC in primary (left) sidebar TOC?

[germa89]

Hi all,

I was wondering if it is possible to include the page table of content (TOC) as part of the global TOC that it is usually located on the primary (left) sidebar.

For instance, given the following files:

directory1/index.md

# Page 1 header
blabla
## Page 1 subheader 1
blabla blabla
## Page 1 subheader 2
blabla blabla

and directory2/index.md

# Page 2 header
blabla
## Page 2 subheader 1
blabla blabla
## Page 2 subheader 2
blabla blabla

So when we build the pages we should have the following TOC on the left sidebar:

when we are on the page 1

directory1
    page 1 header
        page 1 subheader 1
        page 1 subheader 2
directory2
    page 2 header

when we are on the page 2:

directory1
    page 1 header
directory2
    page 2 header
        page 2 subheader 1
        page 2 subheader 2

Is it possible to do that with pydata-sphinx-theme? Would it be interesting to have that feature? I might have the time to code that up.

[germa89]

I guess some changes will be needed in generate_toctree_html function.

[drammock]

we get a lot of requests to change how the theme's TOC / navigation is arranged. For example #1007 #465 #340 #221 #762 #944 #1181. We simply cannot accommodate all possible layout preferences or options.

Regarding this specific request, my hunch is that if we tried to munge the in-page content with the site-wide content, we would end up with some nightmarish layout logic for the (no longer always needed?) secondary sidebar. Have you looked at other Sphinx themes to see if any of them already do this?

[germa89]

My idea is that having a secondary sidebar (right one) in documentation where the pages do not have much headers/sections seems like we are wasting screen space.

For instance, in: https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/install.html

In our case, even more because we had removed the Show source button.

So we have removed completely the secondary (right side) bar, and moved the Edit this page to the right bar also. See https://mapdl.docs.pyansys.com/version/stable/getting_started/index.html

I checked the other themes and they don't seem to include this kind of style (they are all 3-column themes too).

Having the option of including the page TOC in the root TOC will be nice. But I understand that might be a lot work, and we cannot move away from pydata-sphinx-theme.
Anyway, I appreciate your comment.

If you could drop me some links for customising the generate_toctree_html function (how to overwrite it, for instance), it will be great though. So I can explore the possibilities for our specific case.