Make flyout menu scrollable

[mgeier]

I have a project on RTD which has a lot of branches and tags.

When the RTD theme is used, the "version selection area" in the sidebar is scrollable if the window height is too small to accommodate all those links; see e.g. the page https://nbsphinx.readthedocs.io/en/rtd-theme/ (you probably have to change the height of the browser window to see this).

When a different Sphinx theme is used, the "version selection area" is in a "badge" in the bottom right corner of the page. When this "badge" is opened and the window height is too small, there is no scrolling and the top part of the "version selection" is not visible, see e.g. https://nbsphinx.readthedocs.io/en/alabaster-theme/.

This PR tries to make this scrollable.

I'm not sure whether media/css/readthedocs-doc-embed.css is the right place to put this. readthedocs/core/static/core/css/badge_only.css seems to be an alternative location, but I don't know how this is generated.

Maybe there is a much better way to do this. Please let me know any suggestions for improvements.

[stsewd]

Thanks, I think this file is the right place to put that. You may want to take a look at hidden versions too https://docs.readthedocs.io/en/stable/versions.html#version-states

[mgeier]

@stsewd I don't have experience with hidden versions, how do they affect the "badge"?

I just tried a hidden version and I don't see any difference (except for the hidden version not being listed in the list of non-hidden versions).

Or do you mean something else?

[stsewd]

I just tried a hidden version and I don't see any difference (except for the hidden version not being listed in the list of non-hidden versions).

That's the feature yes. This way you don't need to list all those branches that aren't real versions and pollute the flyout menu.

[mgeier]

Ah, now I understand!

You wanted to help me get rid of those versions ... but I don't want to!
I want to have every single one of them.

And I don't think I'm the only one. I've definitely seen other projects with many versions (but as far as I recall, those were using the RTD theme, so scrolling was available for them).

[mgeier]

I think it would be even better if the top part (where you click to close the flyout menu) would stay visible: 7ad8141

[mgeier]

Any opinions on this PR?
Can this please be reviewed?

[mgeier]

Ping?

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[mgeier]

Dear bot, can you please not close this?

[mgeier]

Any news on this?

It has the "Accepted" label but no approving review yet ...?

[stsewd]

Sorry, the team with css knowledge are busy with the site re-design, so it may take a while before reviewing this change.

[mgeier]

Thanks for the update!
I'm looking forward to the new site design!

If this is handled by a separate team, is there a special label or something to mark this PR with?

Anyway, I'll just keep pinging this in more or less regular intervals ...

[stsewd]

I've already requested a review from there.

[humitos]

Just an update here. We are re-designing the flyout and I thought it would be useful to link it to that document here: #8052

[mgeier]

Is there a timeline for #8052?

This PR is a really small change, what about applying it earlier?

It looks like #8052 might take a bit longer, but in the end either way the flyout menu should be scrollable, shouldn't it?

And #8052 doesn't really seem to be about CSS, or is it?

[stsewd]

They are related, but not necessary for this change.

[mgeier]

Ping?

[mgeier]

Any news on this?

[ericholscher]

@agjohnson Would be good to take a look. This does seem like a pretty simple change, so we should 👍 or 👎 it.

[agjohnson]

I'll do a quick test of this, it seems small enough. However:

I'm not sure whether media/css/readthedocs-doc-embed.css is the right place to put this. readthedocs/core/static/core/css/badge_only.css seems to be an alternative location, but I don't know how this is generated.

We don't make this clear at all, but the badge_only.css actually comes from the sphinx_rtd_theme. We copy that file into this repo manually. I've raised breaking this out because it's a really weird authoring and packaging pattern. Alas, these edits do belong there instead, but we could just merge this and backport this to the theme too.

readthedocs-doc-embed.css has a number of hacks that we put in place instead of releasing sphinx_rtd_theme, which feels like a pattern to avoid, generally speaking.

[mgeier]

We don't make this clear at all, but the badge_only.css actually comes from the sphinx_rtd_theme.

And even more confusing, this is only used when the RTD theme is not used, so I would expect it anywhere except in the RTD theme repo.

Alas, these edits do belong there instead, but we could just merge this and backport this to the theme too.

I've tried implementing it there, but I don't know if that works: readthedocs/sphinx_rtd_theme#1297

[agjohnson]

And even more confusing, this is only used when the RTD theme is not used, so I would expect it anywhere except in the RTD theme repo.

👍 I've brought this up as well. I'd like to split this out to it's own repository as well. Currently, it's in an odd spot, as it is using the same underlying styles as the sphinx_rtd_theme flyout

I've tried implementing it there, but I don't know if that works: readthedocs/sphinx_rtd_theme#1297

I started down this path as well, but was having trouble testing it. I hit a block with my local application instance in addition, so had trouble testing anything here. I'll try to return to these PRs this week for testing.

[humitos]

I'm closing this PR. We are working on a complete re-design of the flyout at readthedocs/addons#70