lol, I know I mess things up every now and then, but it's not always me lol

Anyway, I don't think it was me, @thomasjpfan @NicolasHug or @cmarmo may have an idea.

I think it's a sphinx thing and basically depends on whether or not the rst file contains a toctree or not. Those that contain a toctree will expand, those that don't will replace the sidebar.

On this topic, I really like the new pandas navigation system which @jorisvandenbossche has worked on extensively in https://github.com/pandas-dev/pydata-sphinx-theme

I said it was awesome, not messed up ;) @adrinjalali

And yes, I know it's dependent on the structure of the toctree @NicolasHug. I just thought making this consistent might help.

It took me a second to see the navigation on the right hand side for pandas but it looks pretty sweet. The problem with the "consistent" solution I proposed is that for the API and the examples the menu would be very long. Though we could/should also restructure the toc for those. For the user guide it seems to work nicely :)

semi-related: it was pointed out to me that it's discouraging/weird that our examples page starts with "misc examples" which is not very helpful.

For the pandas case, it uses the navbar to change the TOC on the sidebar. For our case, we can argue that the TOC on the user guide should not contain the higher level TOC elements. For example the Glossary of Common Terms and API Elements should not be in the TOC for the user guide page.

Edit: Looks like the pandas theme did a pretty fun hack by monkey patching sphinx to get the TOC to work the way it does.

Edit: Looks like the pandas theme did a pretty fun hack by monkey patching sphinx to get the TOC to work the way it does.

I need to update that readme! Because it is no longer an ugly monkey patching hack ;) Chris Holdgraf turned it into a nice sphinx event callback (sphinx's official support for monkey patching extending behaviour)

Quite obviously, I would love to see scikit-learn make use of the pydata-sphinx-theme, but going to stay out of such discussion, since I am "rather" biased ;)
(and scikit-learn already updated the doc theme recently ..)

That said, I am happy to answer any questions regarding how it works with toctrees (and the theme also certainly would welcome changes to make it more extendable to support customizing it to suit scikit-learn's needs and look and feel)

semi-related: it was pointed out to me that it's discouraging/weird that our examples page starts with "misc examples" which is not very helpful.

We can place the miscellaneous into a folder to make them less miscellaneous. Or a quick fix is to have an Miscellaneous folder just so they are not place at the top.

Edit: Or we rename it to "General Examples" may be a better name.

See also #16601 regarding a better example gallery

Great improvement in #17033 on making the TOC more consistent. I think navigation for items in the User Guide that have more than 2 levels could still be improved. After clicking into the 3rd level, it is difficult/awkward to navigate up a level again and you lose the parent TOC, which is nice, in order to see the overall structure of the docs.

E.g., after clicking into 'Model selection and evaluation' > 'Cross-validation: evaluating estimator performance', you get:

Then, to navigate back up to 'Model selection and evaluation', you can either click on the orange 'up' button on the navigation panel above or, if like me, you did not see that this existed, click on the User Guide on the top menu bar. Edit: for long children TOCs, the orange 'Prev', 'Up', 'Next' panel goes out of view, so the only option to navigate up is to click on 'User Guide'.

Some potential improvement could be to either:

• move the orange 'Prev', 'Up', 'Next' panel to just above the left TOC so it is more obvious
• add another level to the user guide TOC. I don't think this would be ideal as it would make the TOC quite long for some items, but would look something like this for the 'Cross-validation' example:

• use the left global TOC and right local TOC, as pandas etc. I like this though also took a minute to notice the right TOC

cc @thomasjpfan

Yea, I think at this point it will be useful to have the global TOC and a local TOC on the right. Last time I checked, it takes some code to figure the TOCs in difference contexts. Most of the logic is in https://github.com/pydata/pydata-sphinx-theme, specifically here. The theme is used by many projects, I am okay with adopting it in scikit-learn as well.