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

[mgeier]

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

• for already published versions, this breaks the existing integration

  • Broken flyout menu #11663
  • Addons flyout and old versions #11677

• for new versions, even if the theme supports integration of (parts of) the flyout menu (e.g. sphinx_rtd_theme), it still has to be manually activated by site maintainer (e.g. using flyout_display), and the forced flyout has to be manually disabled in the RTD settings.

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]

@mgeier I replied with some more context here: #11677 (comment) -- 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]

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:

• move the flyout to a position where it's less obstructive (as was possible before)
• get rid of the flyout

[agjohnson]

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:

• Should theme maintainers be able to disable or customize default Addons without the project maintainers permission?
• Is it better that projects get a reproducible release of our Addons library, at the expense of not getting new feature/bug updates, or that projects get the latest release of our library but themes can't extend/customize any of our library resources ¹?

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?

Footnotes

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. ↩

[mgeier]

Thanks for the answer. It is hard for me to understand, though, because I was asking about "the flyout" and you are talking about "default Addons" and the "Addons library". I don't know what that means, but I guess it has in some way something to do with "the flyout".

Should theme maintainers be able to disable or customize default Addons without the project maintainers permission?

I don't know, because I don't know what that means, but let me rephrase:

Should theme maintainers be able to disable or customize [change the placement of] default Addons [the flyout] without the project maintainers permission?

Well, yes! That's exactly what I'm asking for above, isn't it?
And it's not really without permission, because the project maintainer selected the theme and therefore gave permission to change the appearance. That's what a theme does, isn't it?

So in case that was unclear: the answer is "yes"!

BTW, you (i.e. the RTD team) changed the appearance without the project maintainers permission! I would just like to restore it.

Is it better that projects get a reproducible release of our Addons library, at the expense of not getting new feature/bug updates, or that projects get the latest release of our library but themes can't extend/customize any of our library resources 1?

I don't know what any of this means.
Can you please explain what any of this has to do with the visibility or the placement of the flyout?

How important is it that themes be able to customize or control Addons for projects using the theme?

Very.

But as I already clarified above, I'm not talking about some generic way of customizing/controlling every part of the flyout, I'm only talking about the placement/visibility.

In case this still isn't clear: the thing is in the way, it is a nuisance!
Not because of the way it looks (that's totally fine), but because of where it is positioned and how it interferes with the content provided by the site author.

If you could control Addons from a theme would you rather customize our default elements or write your own?

I don't really care.

It was really easy before, because I could use rather straightforward CSS to control both the placement (which I care about, and which I changed) and the colors/fonts/etc. (which I don't care that much about, and which I didn't change).

But if you now provide a different way to allow me to change the placement of the flyout, that's also OK.

I'm also OK with getting all the information via JavaScript and place them "manually" on the page (I think there are already examples for that available), as long as, and that's the crucial point (that I think I made already in my original issue description), the theme can then disable the flyout without intervention of the project maintainer.

[agjohnson]

Thanks, that's all really helpful. I get what you're aiming for, and largely agree with this too. Just having this type of input is what will help push forward on our side.

And sorry if I'm not explaining this entirely, I didn't want to blow up this issue with all of the background on this decision. We've had a lot of discussion on this.

To summarize what is happening on our side: we are aiming to only maintain the latest release of our Addons library. There are patterns already available in the library that allow easy customization at the theme level (this includes any customzation, like controlling the position of the flyout and notifications), but these patterns would have to be specified by the theme at build time.

This means these customizations are hard-coded into the project documentation and could decay as the documentation grows out of date and we release new versions of our library. This effectively requires us to support old releases of this library or old attributes/settings/behaviors inside the library in perpetuity.

I'd say it's reasonable for us to treat project Addons configuration as overrides to defaults, and for themes to dictate these default configuration options.

There are conversations about how to safely make this all backwards compatible, I am avoiding getting into here though.

Can you please explain what any of this has to do with the visibility or the placement of the flyout?

This is related to hard-coded customizations in the documentation build and backwards compatibility. Addons customization attributes (like where the flyout is positioned) are mutable and will change over time.

If themes dictate the version we inject for a project, we can't automatically roll out features or security fixes. If themes don't control the version we inject, any theme customization could change when we release a new version.

[humitos]

Hi 👋🏼 . We discussed internally a pattern to solve this use case that suits your needs and our needs as well. I think we reached to something that it could work.

In simple words, the idea is the following:

• Allow theme authors to declare default values for each addon (eg. including <readthedocs-flyout position="bottom-left"></readthedocs-flyout> will tell the addon it should be rendered at bottom left)
• Allow project owners to decide whether or not follow what's declared in the HTML by theme authors. They will be able to select "Position: Use default" or "Position: Top Left" or any other supported value.
• Each addon configuration value will be possible to be overridden by the project owner. So, they could "Use default" for some configuration coming from the theme, but change others.
• By default, all addons configurations will be "Use default". This means that if the theme declares a value for an option, that value will be used. Otherwise, it will be used the Read the Docs' default.

Example

Available options for Flyout:

• Position
• Sorting
• Show latest/stable at the beginning

The theme author declares the following on each page:

<readthedocs-flyout position="bottom-left" sorting="alphabetically"></readthedocs-flyout>

The project owner has the following on the project's settings:

• Position: Use default
• Sorting: SemVer (explicitly overridden by the user)
• Show latest/stable at the beginning: Use default

The result will be:

• Position: bottom-left
• Sorting: SemVer
• Show latest/stable at beginning: True

---

@ericholscher @agjohnson Does this summarize clearly what we've being discussing?

@mgeier What do you think about this pattern? Would it be useful for you to integrate with Read the Docs in a more appropriate way?

[agjohnson]

So far that matches what we've discussed 👍

For the use case described above though, the one missing piece to this is that theme authors might use something like:

<readthedocs-flyout position="inline" />

Or something comparable where theme/project maintainers can explicitly define the flyout position. This isn't implemented yet, just an example.

[mgeier]

Thanks for working on improving the situation!

What do you think about this pattern? Would it be useful for you to integrate with Read the Docs in a more appropriate way?

It sounds promising, but I don't think that "bottom-right", "bottom-left" etc. will be sufficient. As long as the flyout is floating over the content, it will likely be in the way in some situations, especially on smaller screens.

position="inline"

This sounds interesting. Any ideas yet how a theme author could then define the flyout position and how it is integrated in the theme?

[agjohnson]

For all of this theme control, theme authors would directly use the web components that we ultimately add automatically.

So, if theme maintainers want the flyout to display inline at the bottom of a navigation menu, the theme's templates might have something like:

<body>
  <nav>
    <div>....</div>

    <div class="nav bottom">
      <readthedocs-flyout position="inline"></readthedocs-flyout>
    </div>
  </nav>
</body>

Inline display specifically will probably require some careful CSS on our side, but it feels doable.