Answering to #6402 (comment) here.

@nicoddemus @The-Compiler

I do like the RTD theme, but its sidebar seems quite messy compared to our current one - is this something we could port over to the RTD theme as well?

https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html#how-the-table-of-contents-displays

Not sure how to configure it properly though...

It uses our TOC tree, which is not well organized it seems: https://github.com/pytest-dev/pytest/blame/ca8a1e47b0cc7fe44851b83ae0d225bf5b13e55d/doc/en/contents.rst#L10
(a lot via 519f02b (#1112) it seems)

Previously this was used: https://github.com/pytest-dev/pytest/blob/60f09d4600ebdc884fa5b8d2b20258a72e69b918/doc/en/_templates/globaltoc.html

It could still be used with the new layout, e.g. by extending/overriding the default blocks probably: https://github.com/readthedocs/sphinx_rtd_theme/blob/68a19ca510ca67fc0afefce155544ee008a23aa7/sphinx_rtd_theme/layout.html#L148-L169

It might be better to re-structure the TOC in general though, so that it ends up in maybe only 10 top level documents.

Thanks @blueyed for investigating this further!

It uses our TOC tree, which is not well organized it seems

Why do you say that?

The objective of that reorganization was to have "flatter" topics so they are easier to find, from #1112:

I always found the pytest docs quite hard to navigate - and because of someone with the same issue in IRC just now I realized why: The stuff which is probably most relevant (assert.rst and fixture.rst) is hidden on examples.rst but not mentioned at all in content.rst.

Of course a flat organization like that does mess the sidebar with this theme, but that IMHO is a fault of the theme that doesn't allow it to be customized like we did with the previous globaltoc.html file.

It could still be used with the new layout, e.g. by extending/overriding the default blocks probably: readthedocs/sphinx_rtd_theme:sphinx_rtd_theme/layout.html@68a19ca#L148-L169

Oh that would be great! I don't really know how to do that though. 😬

If you are willing to give this a try, please feel free to push into this branch directly. 👍

It might be better to re-structure the TOC in general though, so that it ends up in maybe only 10 top level documents.

But then we are back to the original format, which was hard to find things...

It might be better to re-structure the TOC in general though, so that it ends up in maybe only 10 top level documents.

But then we are back to the original format, which was hard to find things...

I've not really looked into how it looked/appeared before, but thought that 519f02b#diff-6f267ce6423005e07dd261cb63ec96fa was just dumping it all into the top level.

IIRC you are right, while also changing the order so things make more sense.

So the blocker here is that we have no structure for the docs apparently.

Should we use the current sidebar as top-level elements then?

Closing in favor of #6453