[docs] ToCs are empty or incomplete, wasting screen real estate

[sneakers-the-rat]

(raising this here as requested in https://github.com/zarr-developers/zarr-python/pull/2142 )

All these comments are based on current version of v3 docs: https://zarr.readthedocs.io/en/v3/index.html

Currently on the each page (using the tutorial for example here), the primary sidebar is totally empty or contains a single item. on wide screens, this is sort of a curiosity, but it becomes a nuisance on narrower screens. More than anything is just looks weird and unfinished (not your fault, byproduct of the theme)

Wider than medium breakpoint:

Below medium breakpoint:

There is also a related problem where the "index" pages within a section don't appear like indices, eg. https://zarr.readthedocs.io/en/v3/getting_started.html contains an "installation" subpage, but the main body of the page doesn't make that obvious.

The basic issue is that pydata-sphinx-theme has a specific notion of sections that has a double nesting of section -> sectiontoc -> localtoc, where each of the sections (eg. "getting started," "tutorials," etc.) is expected to contain a number of other subpages, but currently they all only contain a single page.

One answer is to just remove the left sidebar ( https://github.com/zarr-developers/zarr-python/pull/2142 ), another is to move the in-page toc to the left sidebar (also described in #2142 ), or thirdly one could split up the content of the sections into multiple pages.

We have experienced this double nav being confusing in other projects that use pydata-sphinx-theme (eg. https://github.com/pyOpenSci/python-package-guide/issues/267 ), because the norm is to only have one navbar, and the right sidebar collapses at medium widths and isn't obvious on mobile, where you get two menu bars to choose from:

[d-v-b]

Thanks for raising this issue, I agree that that empty left navbar is unsightly.

because the norm is to only have one navbar

At least for the doc sites I frequent, I think the double navbar is fairly common -- see the numpy docs or pydantic docs or tensorstore. Those projects make it work, so I think the zarr-python docs are just doing it wrong, and my proposed solution would be to re-organize the docs so that we use both navbars properly.

[sneakers-the-rat]

At least for the doc sites I frequent, I think the double navbar is fairly common

totally ya, sorry what i wrote is slightly off what i meant - with those projects the scale is slightly different, where there are tons of pages so you expect to use the topbar for global navigation between sections, leftbar for navigation between pages within sections, rightbar for within page. so maybe closer is 'expectation is to have a hierarchy of navs s.t. the in-page toc becomes more obvious when the between-page tocs are obvious'

[jhamman]

closed by #2142