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 :)