search

readthedocs / readthedocs.org

The source code that powers readthedocs.org
https://readthedocs.org/
MIT License
8.03k stars 3.58k forks source link

Please provide a way for Sphinx themes to "take over" the flyout menu #11688

Open mgeier opened 1 week ago

mgeier commented 1 week ago

The forced activation of the new flyout menu is doubly annoying:

I have kinda accepted that old versions of the docs will get the distracting new flyout, but the problem is that since it has to be disabled for new versions (and it can only be disabled for the whole project), it will also be disabled for old versions. And even though the floating flyout is annoying, it is still better than having no way of switching between versions!

So my wish is: please provide some way for theme authors to provide whatever integration they want (as I think is available already), and make it possible for a theme to disable the floating flyout for the current version where this theme is used (without requiring site maintainers to change their RTD settings).

This would mean that old versions get the floating flyout (annoying, but acceptable), but new versions get whatever the theme authors intended (which most likely means no floating flyout).

ericholscher commented 1 week ago

@mgeier I replied with some more context here: https://github.com/readthedocs/readthedocs.org/issues/11677#issuecomment-2417591367 -- but the goal is for theme authors to integrate the data in the flyout into the themes more than integrate the entire flyout in the future. This is why we haven't built a ton of customization into the flyout, since all the data is accessible and can be injected. We're willing to work with you on a temporary solution that uses this data where we can modify the behavior on your old versions to try and manage the transition, but please let us know if that is a reasonable approach.

mgeier commented 1 week ago

Thanks for the answer, @ericholscher!

I know that theme authors can obtain the data and put it wherever they want to, that's what I was trying to say with "as I think is available already". But what I'm more interested in is the second part of my wish:

and make it possible for a theme to disable the floating flyout for the current version where this theme is used (without requiring site maintainers to change their RTD settings).

Are you planning to provide such functionality?

This is why we haven't built a ton of customization into the flyout, since all the data is accessible and can be injected.

I'm not so much interested in what's in the flyout (that looks fine and works as intended), but where it is placed. It's just always in the way!

I would like for a Sphinx theme to be able to do one of two things:

agjohnson commented 3 days ago

Are you planning to provide such functionality?

So, short answer: this was the initial intention, the library already supports some of this, but we're struggling with what we want to actually support and haven't done a great job promoting these patterns.

This has been a frequent subject in discussions, and this would be a really useful place for feedback right now. The discussion behind this is quite complex, but the two issues we're struggling with are:

Currently, each individual project must manually disable Addons regardless of whether their theme supports RTD or not. Themes cannot customize Addons for individual projects.

How important is it that themes be able to customize or control Addons for projects using the theme? If you could control Addons from a theme would you rather customize our default elements or write your own?

[^1]: When I say library resources, I'm referring to variables, classes, attributes, methods, web component properties, and CSS variables. These all might vary between library releases and so this is why themes can't rely on them.