Show TOC from root index.html on left sidebar

[jrbourbeau]

I'd like to show the TOC for the root page (index.html) on the left sidebar and was wondering if it's currently possible to do so. Today the sphinx TOC appears on the left sidebar for index.html pages that are in subdirectories, but not the root index.html page.

├── index.rst        <-- TOC not in left sidebar
└── inner_section
    ├── index.rst    <--- TOC is in left sidebar
    ├── ...
    └── ...

As an example, see the pydata-sphinx-theme documentation page:

• pydata-sphinx-theme root (index.html)
• pydata-sphinx-theme user guide page (user_guide/index.html)

[choldgraf]

just to clarify - do you mean in addition to the links at the top, or instead of the links at the top?

[jrbourbeau]

In addition to the links at the top. I was envisioning a more detailed TOC on the left sidebar, e.g. :maxdepth: 2, but still having the links at the top like all the other pages.

[jorisvandenbossche]

Today the sphinx TOC appears on the left sidebar for index.html pages that are in subdirectories, but not the root index.html page.

That is because for the root index.html, this TOC is actually already shown, but in the header.

This theme basically tries to look at the global toctree of the full sphinx site, and the puts the first level in the top header bar, and the second (+ potentially third) level in the left sidebar.

There are variants possible where all levels of navigation are put in the left sidebar, see eg #90

[jorisvandenbossche]

In addition to the links at the top. I was envisioning a more detailed TOC on the left sidebar, e.g. :maxdepth: 2, but still having the links at the top like all the other pages.

But so for the root index.html, which more detailed TOC are you thinking of?
Eg for https://pydata-sphinx-theme.readthedocs.io/en/latest/index.html, there is no more detailed TOC for the home page. There is only a more detailed TOC if you choose one of the top-level pages (on the root index.html, none of the first-level navigation items are active, so we can't choose which second-level navigation items to show)

A more concrete example would probably help to try to clarify what you mean or want to achieve.

[choldgraf]

I think it could be beneficial to have top-level links there only for the landing page, just to avoid having that kinda awkward white-space?

Note that this will be quite easy to special-case for the master_doc page if #219 lands.

[jorisvandenbossche]

I think it could be beneficial to have top-level links there only for the landing page

But which top-level links? Repeat the ones of the header bar?
That is a possibility, but might also give a strange duplication?

To be clear, I fully agree the home page right now is not looking good with the empty side bar, but I think a more custom design might be the better solution (-> #146)

[choldgraf]

Repeat the ones of the header bar?

yeah that's what I had in mind. I agree it'd be a bit weird to duplicate them though

[jpmckinney]

I don't think it makes sense to repeat navigation.

To fill the space, users might want to configure html_sidebars to display some homepage-specific content instead (e.g. the organization behind the project, sponsors, community links, whatever).

Alternately, the homepage might be fuller width.

[choldgraf]

@jpmckinney agreed - I think this issue came up before the html_sidebars was supported, but now that it is perhaps this is less of an issue. @jrbourbeau what do you think?

[jonnew]

I would like to have a left side bar on the top level page to show other top level pages that are not master_doc/index.html. For instance, I have a FAQ and contact pages. Making an entire top-level "About" entry in the nav-bar for those two pages feels kinda strange. I would rather have the ability to link them in the side bar of the main page. Although, this might be a different issue as I don't want to repeat what is in the top bar on the side.

[drammock]

@jonnew have a look at what MNE-Python does: the html_sidebars configuration (here) lets us specify a couple items (the custom one is here) that only show up on the homepage's left sidebar; other pages get the default TOC in the left sidebar.

[jonnew]

@drammock That's exactly right. Thank you!

[maximlt]

Looks like we've managed to achieve what the OP wanted on one of our websites (https://holoviews.org/index.html).

And when I see it in action I think it's a better default than the empty sidebar. It also allows to get to a specific page more quickly (by expanding an item).

I would actually like to replicate that on each one of our sites, the problem is that I really have no clue how the TOC ended up being displayed in the sidebar on this site 🙃