Left navtree not showing subheaders (only subpages)

[ErikBjare]

In our current docs for ActivityWatch (https://docs.activitywatch.net) we use subheaders to make the docs easier to navigate from the navtree to the left.

I've been meaning to migrate away from the RTD theme to something more plain/modern (like this theme), but I noticed that only subpages, not subheaders, show up in the navtree. There is the tree to the right, which does serve a similar purpose, but I'd rather have the entire TOC (including subheaders) in the left navtree.

I can understand how the existing behavior suits some docs better, but in our case it's not a great fit.

Is there a way to get the desired behavior through config (can't seem to find a way) or could someone point me to where the RTD theme and this theme differs in how they handle the navtree?

If I made a PR incorporating such a change as a config option, would it get merged?

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[ErikBjare]

I now realize this might be an upstream matter for the pydata theme, and the choice seems explicit by the devs: https://github.com/pydata/pydata-sphinx-theme#the-html-layout

Should I close this issue and open a new one there perhaps?

[ErikBjare]

From further inspection of the code, it looks like this is controlled by titles_only:

https://github.com/executablebooks/sphinx-book-theme/blob/c205a9e57e15ea4d6faeea37ff3be292cd2e5b71/sphinx_book_theme/__init__.py#L100

Could we make this configurable? (similarly to https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html#confval-titles_only)

[choldgraf]

Sorry for the slowness on this one - but a quick clarification: if sub-headers were included in the left instead of on the right, then would you also expect the in-page TOC to show up on the page? Or would you expect it to disappear because the page sections were now listed on the left instead of the right?

I'm of two minds on this one - I understand the value of having headers on the left, on the other hand I feel like this is a "theme choice" and we can't make every UI element configurable or we'll run down a neverending rabbit hole 🤔

[flying-sheep]

So this is still hardcoded: https://github.com/executablebooks/sphinx-book-theme/blob/c47d8e46fbce78492abd8a5adfe41083bb7ba121/src/sphinx_book_theme/theme/sphinx_book_theme/components/sbt-sidebar-nav.html#L21

Can you please make it configurable?

[ivirshup]

To document a use case here, I would like to have a "fancy directory" page like this:

https://scanpy.readthedocs.io/en/stable/tutorials/index.html

Without needing to have this page, and definitely without this page being user accessible:

https://scanpy.readthedocs.io/en/stable/tutorials/basics/index.html

This is especially important for API listing pages, where each function has it's own page, but we can't group methods within the TOC without having a dedicated page for each grouping.

• Example from scvi-tools

I am broadly sympathetic to the design choice "pages on left, current page headings on right". I have definitely been subject to some documentation where these levels are mixed in a way that is confusing.

However, I think the "narrative TOC" use case is pretty useful, but so is quick navigation to subpages it contains. I think it could be worth having a narrow exception made here. For example, letting a :caption: show up as a node in the left TOC tree. I believe an explicit escape hatch (like I think Furo provides: https://github.com/pradyunsg/furo/issues/88) could also work.