I totally agree that the current index is way too much information. Towards that, this is a significant improvement. However, I'm not a fan of using dropdowns here, because you have to click a lot to know where you may want to be going. I'd rather shorten the list of targets. One may or may not still have visual grouping or panels or whatever to make the GUI look nicer.

Shortening: For a number of the sections, we don't need to reference the subsections on the overview page. For example, linking Installation is enough. We don't need all the subsection links. They anyway go to the same page, which has the TOC in the sidebar. It's better to just click Installation and be on the page and then use the naviation on that page.

Fancy GUI: For example for the "Tutorials and examples" section, I suggest three clickable cards in a row (https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/web-components.html#cards).

Tim your suggestions are great but at that point this page is then just recreating the docs landing page and then the question is does more of this stuff need to get pushed there and then this page can go away? Which like I wouldn't disagree with either...but while this page exists some of my reasoning for including the level 2 TOC is so folks can browse through them and see if the installation page is really what they want.

I think the User Guide Page is a bit of a misnomer, but that aside, I prefer the information content unfolded as it currently is. I think it's unattractive, but it's pretty easy to skim for the correct information, whereas folding hides a lot of content. A multicolumn layout or some such would be fine, but I think the more fundamental issue is the awkward match between the rst docs and the tutorials/gallery; much of what is in the tutorials would more logically be called part of a Users Guide.

it's unattractive, but it's pretty easy to skim for the correct information

I have the opposite problem - I find it really overwhelming and like being able to unfold as I go. But maybe grids + styling the cards so they look more like accordions? I'm trying that, might be a bit cause the icons are annoying.

I think the more fundamental issue is the awkward match between the rst docs and the tutorials/gallery; much of what is in the tutorials would more logically be called part of a Users Guide.

FWIW I think that moving the tutorials to use sphinx-gallery was a mistake -- s-g works well for short examples, but the "tutorials" are (should be?) first and foremost text, with some code interspersed, for which the plot directive works just fine (especially with download icons, per #24205 (comment)); moving back to plain rst should simplify better organization.

Either way, I think this is too big to backport.

I am sympathetic to both the pro and con to switching to the foldable things. Can we start all the folds open? That way if people just want to skim they can and there is an easy way to hide things that you have already looked to reduce the noise?

Yes but I think this actually looks pretty good/less a lot than I thought it would be:

ETA: I put this view in the second commit. I can't quite sort out the .css to remove all the styling though.
ETA2: circle link

So decided to shuffle a bit b/c I think it focuses things a bit and kinda ties into Anthony's point that our tutorials/narrative docs boundary isn't as clean as the divio structure:

I am not at all sure about the section titles but these are more or less the ones currently there. I'd possibly even get rid of them since they don't show up in the sidebar since they're card titles.

And 3rd commit is a full shuffle based on how my brain works:

👍 on the structure

Still not on board with the dropdowns. We can't leave vast amounts of white space and force the users to expand everything manually:

Obviously a taste thing, but I usually resent drilling down webpages to find things. I think we can use styling or better bullets etc to make the page less overwhelming.

On my computer there's almost no white space, but I'll tweak drop downs to be open by default and maybe styled plain and then I'll post that screenshot.

So joy, lots of white space on my big screen, none on my laptop screen :/

I think with default open it's probably better to keep the styling: (ETA: also I can't figure out how to change it 🙃)

ETA: Also like I want to change all the titles and stuff so everything is in a similar voice/tense but totally out of scope here.

This page claims to be the user guide but is actually more a table of contents of the whole page.

Yeah totally agree, and I think the real solution is some combination of information architecture and something in line w/ what @anntzer and @jklymak are saying about how our tutorial/guide boundaries are fuzzy and I think could be consolidated/unified, but I think that's maybe a good GSOD proposal if there are RFPs in February.

I wouldn't mind this not being in the navigation bar or renaming the link to documentation. Um is mpl.css the right place to add the styling or should I be using something else? Also if we want dropdowns anywhere else, I think I'm gonna have to package everything into a class.

8?th commit is cards + dropdowns, but styled so it's kind of invisible/looks like the toc-tree:

I am very much not a fan of the user guide page title here but couldn't figure out how to get the html title working. Also, removing the title adds back the left sidebar

The problem with the screenshot above is that the title of the subsection has a smaller font (though demi-bold) than topics below them. That makes it pretty hard to parse and looks like a mistake.

I can try putting a color or something back in? my goal was that when closed it wouldn't look cluttered:

I think there is plenty of room for the heading font size to be larger. But certainly you should not have the heading font size smaller than its content.

Ok, so this is just everything is one size up

Hmm, I think w/ an indent, size becomes good enough to not need the grid top: (which @timhoffm I can't figure out how to do)

Edit: Also while not 100% accurate, "Information, Explanation, Reference" might be good enough?

Ok so @timhoffm I did figure out the border but probably in the hackiest way and I'm cool w/ commits against this that tweak styles more.

Ok so @timhoffm I did figure out the border but probably in the hackiest way and I'm cool w/ commits against this that tweak styles more.

I can have a look, though I’m not a CSS expert either. But likely not before the weekend. This is not necessarily a blocker. We can always fine-tune in a follow-up PR.

No idea why/what I did differently but now the borders don't disappear on fold up but this is commit 9

Since this has kind of run away, @melissawm and @noatamir what suggestions do you have about organizing this information? Particularly do these categories make sense, a different taxonomy? Also please help me name things if you have suggestions.

What is the current state of this PR?

Oops sorry I had lost this ping! Let me respond below.

@tacaswell not sure which of the 6 options (if any) folks are leaning towards & if this is enough of a UX improvement to be worth going in, and I probably should pull the styling into its own class.

The concrete question is do we try to get this in for 3.7 or push this out to 3.8?

@tacaswell let's put it on the call?

I'm fine w/ pushing this out to 3.8/scrapping it in favor of a better UX suggestion, but if it doesn't seem like that's gonna happen in the next couple of release cycles than I can try and wrap this one up this weekend if we've decided on styles and names.

So talked w/ @melissawm offline and thinking an alternative proposal is to use the cards/grid to make a holistic TOC of sorts and keep the level two trees underneath so that folks can skim for holistic or all the things.

At this point, would make more sense to open a new PR with some of the distilled ideas.