Page toc (right sidebar) content and styling

[jorisvandenbossche]

Apart from #8 on collapsing the sections that you are not viewing, there are some other things we might want to do for the right sidebar.

We can use this issue to gather some ideas.

[jorisvandenbossche]

Some other things we might want to put in the right sidebar:

• A "On this page" or "Table of contents" title, to make it clearer what this navigation is exactly
• A "Edit this page" link

Example from docker (see eg https://docs.docker.com/engine/reference/commandline/dockerd/), although here it is rather crowded with additional things:

Jupyter book also uses a "On this page" in the right sidebar (eg https://jupyterbook.org/intro):

[mangecoeur]

Adding 'On This Page' would definitely help make it clearer - although the Jupyter example has its own problems (namely that there are two unrelated navigation hierarchies in the left and right panes - more of a navigation bush than a tree >_< )

Probably worth listing (at least for reference) the pros (and cons) for the left/right split navigation vs the collapsing tree navigation of the old docs. My own take:

• now that the 'top level' nav is in the header there would be more space in the left pane for a classic tree nav, which would be simpler and always shown

• by using the right nav, more sub-levels of the navigation tree can be show, which lets the docs grow without becoming impossible to navigate because you can always jump to sub sections.

[jorisvandenbossche]

Thanks for your considerate thoughts!

I think it is clear that it is useful to get to the subsections of a page through the navigation (at some point we briefly disabled this: pandas-dev/pandas#25131). But the question is where to put them.

Before we had a single (left sidebar) navigation structure. In this theme we opted for 3 (top navbar, left sidebar, right sidebar). It's certainly true limiting to 2 structures would already be an improvement over the old situation IMO.
(and it's also subjective, personally I like the 3 navigation elements, but I know others of the team find it "too much". It maybe also depends on the way how you use the docs)

Reasons that I prefer to have the "within page toc" and sidebar separate:

• When showing the page toc also in the navigation tree on the left, this quickly bcomes a long tree for pages that are somewhat longer. In the old theme, on some pages, this means that the full tree doesn't fit on my screen (eg on https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html). And removing the top-level (what is now in the top navbar) only improves this slightly, and for the example above, it would still not fit on my screen (certainly if you make the font a bit larger, which it is in the new theme).

• I would like to split some of our very long pages into multiple pages. While that makes the previous argument potentially moot, I would like to do this by introducing an extra level in the navigation. Eg now, you have "User Guide" -> "IO tools" (2 levels). I would like to split the big IO page into multiple pages by introducing a third level. This means that the left sidebar would also already show 2 levels (see eg https://dev.pandas.io/docs/getting_started/comparison/comparison_with_r.html, where we already have this). In such a case, also showing the within-page toc in this left sidebar, would make it very nested (certainly if you want to show more than 1 additional level of the page).

[jpmckinney]

"Edit this page" and "On this page" are implemented, e.g. https://pydata-sphinx-theme.readthedocs.io/en/latest/demo/demo.html

Should this issue be closed?

[choldgraf]

Yeah I think so, we can open up new issues for specific ideas to track more easily I think