make sidebar sticky

[v-python]

All the relevant comments are over there https://bugs.python.org/issue28044 which got closed as soon as I added my comment, which isn't a particularly friendly sequence of events. If the issues there are outdated, they should be marked outdated and transferred here as part of the transition.

My comment is that the sidebar menus scroll off the top when you scroll down the page, so they are pretty useless, instead of helpful.

Nice implementation of sticky sidebar.
https://css-tricks.com/sticky-smooth-active-nav/#more-273952

I haven't looked at the patch, and don't know what R. David Murray doesn't like about how it works, but I find the Python sidebar extremely annoying because it scrolls off the top, and would rather it stayed around visible.

[theacodes]

Hi @v-python, sorry you had a not-so-friendly experience reporting this!

In terms of stickying the sidebar, it's problematic because many time it prevents navbars with lots of items from being completely visible or users with smaller screens from seeing the entirety of the sidebar. Do we have any solutions to that?

[v-python]

Sidebar content can be in independently scrollable container, with no constraints on height, limited to window height. If the window height is big enough for the sidebar content, no scrollbar appears. If the sidebar content exceeds the window height, you get an extra scrollbar for it.

[v-python]

And that would allow you to scroll the sidebar content while still seeing the main content where you were, which might be helping to give you context for what you want to look for in the sidebar. And another annoyance I've had... you scroll to top to search the sidebar, but lose the context of where you were, if you don't find what you were looking for in the sidebar, and want to return to where you were in the main content, but you had to scroll away to find the sidebar.

[pete312]

i reported this as a bug in 2018-05-07 https://bugs.python.org/issue33442. Do you need help resolving it ? I feel it should be easy to replicate and resolve as the python 2.7 documentation theme works fine.

[theacodes]

Do you need help resolving it ?

Yes, this is a volunteer project. We're happy to review pull requests.

[theacodes]

I'm also still skeptical of this change being "the best thing to do". @Mariatta, what are your thoughts?

[mariatta-bot]

Mariatta was mentioned, but she's out of open source for the rest of September 2018. Be aware she might not get to this until October 2018.
(I'm a bot)

[JulienPalard]

There's a patch in an issue on b.p.o here https://bugs.python.org/issue24712 that looks to work for 2.7.

But nothing works in 3. We definitively need help here, front-end is not my thing þ

[JulienPalard]

There's an almost duplicate of this issue on b.p.o : https://bugs.python.org/issue32393, I mean if we make the menu sticky, let's not make it jitter.

[JulienPalard]

We merged the patch from https://bugs.python.org/issue24712 to the 2.7 branch it should no longer flicker. Still have to fix Python 3 version (I don't know how to do it).

[dlukes]

So this has been a fun bit of archaeology :) If you'll indulge me:

Once upon a time, the custom CSS for the Python docs theme lived in a single file, Doc/tools/sphinxext/static/basic.css, and all was well.

Then, the docs switched to a new, lighter design, which introduced a second CSS file, Doc/tools/sphinxext/pydoctheme/static/pydoctheme.css. For a while, these two files lived alongside peacefully.

Some time thereafter, someone noticed that the TOC in the sidebar was wont to ascend to the celestial heavens when scrolling the document, which made it inconvenient to quickly navigate it. Time and again, one had to scroll back to the top to peruse the TOC:

status_quo.mp4

_{(We're currently back to this state as of a7b271a.)}

And there was much furrowing of brows and stroking of chins, which resulted in intelligent scrolling being implemented unto the sidebar. And there was much rejoicing, for the sidebar would now stay to the side, instead of disappearing Up and Out:

intelligent.mp4

_{(This state can be recreated with dlukes@6d16fb2.)}

But lo! A fatal flaw slipped into this laudable endeavor. Crucial CSS properties were added to the older of the two CSS files instead of the newer. In due time, that older CSS file was removed, as it had run its course, and those crucial CSS properties with it. Without them, intelligent scrolling became but a shadow of its former self. Which is to say, it didn't work at all.

In the meantime, people had started noticing that intelligent scrolling was prone to make their browsers all jittery. Even the Firefox Developer Console oracle was complaining "This site appears to use a scroll-linked positioning effect.", in the amber tones of a mild admonition. This was because intelligent scrolling relied on the dark arts of JavaScript to work its scrolling magic. And there was much complaining and hand-wringing. But web standards had evolved, and it was now possible to use modern CSS features, like the almighty position: sticky, to achieve the same functionality, so the Python docs did, at least for version 2.7.

Except in a dark twist of fate, it turned out this fix wasn't actually equivalent! For it made the sidebar completely unscrollable. And so, if it was higher than the viewport, the nether regions of the TOC became entirely unreachable:

sticky_broken.mp4

_{(This state can be recreated with dlukes@3ec5872.)}

---

I'll drop the storytelling tone, as it probably stopped being funny a while ago, if it ever was :) Key takeaways: the original "intelligent" scrolling can be easily restored, but it can be jittery and people seem to mind, so it's probably not worth it. Plus it's actually somewhat inconvenient, since if you want to scroll the TOC, you have to scroll the main document too. Replacing it with position: sticky can work, but the fix used for the 2.7 docs results in the sidebar being completely unscrollable, which can make content at the bottom inaccessible.

Instead, I propose the following "dumb" scrolling approach: use position: sticky (which makes the sidebar stay put) in combination with overflow-y: auto (which makes a scrollbar appear if the content overflows the viewport). The user can then freely scroll both the sidebar and the main content, each separately:

dumb.mp4

_{(This state can be recreated with dlukes@5ee3053.)}

As a bonus, this gets rid of the warning in the Firefox console.

For older browsers (which don't have position: sticky or viewport units), this should fall back to the current behavior where the TOC simply scrolls out of view. Which I wouldn't exactly call graceful fallback, but since that's how it has worked for years now, people shouldn't be too miffed about it. Improving the UX at least for modern browsers is still a net win IMHO.

Ultimately, this commit is what I ended up with. Can I open a PR? I really should have been doing something else today, but I got bitten by this annoyance one time too many, so here we are -- I'd at least like to make it count :)

[dlukes]

Can I open a PR?

I guess I'll just do it and we'll see how it goes :)

[JulienPalard]

@dlukes Hahaha, thanks for the story time, I always appreciate archeology!
(And thanks for working on it, will take a look at the PR!)