[UX] Improve confusing split navigation

[zackw]

I didn’t even see the second table-of-contents sidebar on the right side of each page until after I’d gotten lost clicking around in the left-hand sidebar. I’m still a bit confused but I think the left sidebar has the TOC tree above the level of individual HTML pages, and the right sidebar has the section headings for the current page. I think it would be much less confusing if the left sidebar included the section headings for the page you’re on, nested under the page’s title.

[lwasser]

hey @zackw were you sprinting on pyOpenSci via pycon US last week or did you just find us and are contributing to the guide that way? I'm organizing issues and such and was curious how you found us.

also welcome to pyOpenSci!

[zackw]

yes I was at the sprint last monday

[lwasser]

oooh @zackw of course you were. the owl triggered my memory! i should have looked at your profile as the gh usernames get blurred in my mind! my apologies.

[willingc]

Hi @zackw, Nice to see you here. Thanks for the usability suggestion. The location of the left and right navigation is a function of the theme. I do think we could do an override on the theme to make the headings more explicit. We could likely replace Section Navigation with a more descriptive term. Open to suggestions on the wording of a different title that more clearly reflects that it is listing the main navbar category contents (i.e. Tutorial).

Left

Right

[lwasser]

@willingc @zackw that split navigation has always driven me crazy. it also visually is confusing. is there a way in sphinx to add the sub sections of a page to the left hand side bar? i'm guessing we could do that. i'm pretty sure there is an option to turn off the right side! because i remember opening an issue on this a few years ago.

i agree it's too much visually especially if you need larger fonts on the screen (which i do).

i'm guessing there is a way to do this so the sub sections are just added to the left side when you are in a page. i'm going to bug @choldgraf (i hope you don't mind chris!). I try hard to rarely ping you!

I just suspect that you know the answer here and could guide us!

[choldgraf]

It's possible in sphinx for sure (the ReadTheDocs theme does this for example) but I don't believe it is yet possible in the pydata theme. Probably would require an enhancement issue to see if others are interested in this too

[lwasser]

got it. thank you @choldgraf !! 🚀

[sneakers-the-rat]

If i'm getting the question right, we want to just move the in-page TOC to the left side? I think that you can do this with pydata-sphinx-theme like

html_theme_options = {
    # ...
    "secondary_sidebar_items": {
        "**": []
    }
}

html_sidebars = {
    "**": ["page-toc"]
}

weirdly i literally was just doing this: zarr-developers/zarr-python#2142

(but i mean don't take my word for it, i'm assuming i'm missing what's being asked here because chris wrote the dang thing so he obviously knows better than me)