Enable announcement banner to be sticky

[alexisthual]

What's happening?

Currently, I use the announcement banner to warn users that they are looking at an outdated version of the generated docs. However, the banner is not sticky / fixed, so it disappears when users scroll down the page. This can be problematic when users access the docs through a hyperlink referencing a paragraph, as they probably won't see the banner.

I tried using custom CSS to simply make the banner sticky, but it seems it seems more complex (see discussion #545). In particular, the rest of the page will scroll under the banner, eventually hiding the logo, which I think is not the expected behaviour.

Reproducer

Simply use announcement option and scroll down.

Expectation

In my opinion, banners should be sticky by default in order to prevent this, but I guess having an option to make them sticky or not could be nice! :slightly_smiling_face:

Code of Conduct

• [X] I agree to follow the Code of Conduct.

[davidism]

I would like to have this as well. I'm hoping to adopt Furo as the base theme for Pallets projects and Flask.

We have a sticky banner when viewing old or dev docs, you can see an example here: https://flask.palletsprojects.com/en/2.2.x/views/#view-decorators. It's sticky so that no matter where a user is linked to in the docs, they see the banner with a link to the current docs. I wrote some JavaScript to prevent it from overlapping headers when linking to an anchor as well as when clicking anchors on the page: https://github.com/pallets/pallets-sphinx-themes/blob/529e8fc362d99f600057fe78ffbe24a11f442276/src/pallets_sphinx_themes/themes/pocoo/static/version_warning_offset.js. It works on large and small screen sizes.

I tried using Furo's announcement for this, but when I tried to make it sticky I ran into a few different problems:

• Unless I move the element inside the page div (instead of a sibling), it eventually scrolls away (I think when the sidebar conents height is reached, but not sure).
• At small screen sizes, Furo makes its header sticky. This needs to be pushed down with top: var(--header-height), otherwise it overlaps the announcement.
• It overlaps headers when navigating to or clicking anchors. Furo's sticky header doesn't overlap, I think gumshoe.js is handling this. Gumshoe is initialized with a function that calculates the height, so it would need to be adjusted similarly to the previous point to account for both the sticky header and announcement.

[Eric-Arellano]

FYI this is the CSS we needed to add a sticky top nav bar to qiskit_sphinx_theme, which builds off of Furo:

https://github.com/Qiskit/qiskit_sphinx_theme/blob/765c936a6b285c537e8cb9247d4b84862b8417a8/qiskit_sphinx_theme/furo/base/static/styles/qiskit_changes.css#L121-L175

HTML change:

https://github.com/Qiskit/qiskit_sphinx_theme/blob/765c936a6b285c537e8cb9247d4b84862b8417a8/qiskit_sphinx_theme/furo/base/page.html#L9-L11

We use these visual regression tests from Playwright to make sure we aren't breaking things. That is, these are the edge cases we found that a sticky top element breaks:

https://github.com/Qiskit/qiskit_sphinx_theme/blob/765c936a6b285c537e8cb9247d4b84862b8417a8/tests/js/snapshots.test.js#L60-L139

And indeed, gumshoe.js is broken for detecting the current section in the right side bar. But we're hoping that @pradyunsg will be okay with merging https://github.com/pradyunsg/furo/pull/664, which would fix the problem.