Make sidebar TOC sticky and visible through out the document

[pllim]

Original post from @smoh at astropy/astropy#8941:

Hi, I was looking at various documentations of astropy-related projects which uses astropy sphinx theme and have a suggestion. I thought it might have come up already but couldn't find any. It is related to #8922 but not exactly the same issue.

Is it possible to make the sidebar sticky and have its own scroll as in here in python 2.7 docs? Right now, when we scroll down, the sidebar scrolls down with the content quickly becomes invisible letting its navigation utility not so useful except at the beginning.

Oddly, python 3 docs sidebar also scrolls down with content and there is a relevant thread here: python/python-docs-theme#20

I don't know enough css/javascript to gauge how easy/hard it is but it would be so nice.
(I thought this issue belongs here than astropy-sphinx repo but please feel free to move it if appropriate).

[kakirastern]

Think this is being dealt with in #12. A commit has been added to #9 to correct for the non-sticky scroll sign behavior. The solution suggested therein seems to work. Suggestion summarized in #12 (comment).

[smoh]

No, this is not related to issues raised in #12.

It is a feature request to make navigation sidebar sticky as in (just two examples)

• https://docs.python.org/2/library/index.html
• https://docs.readthedocs.io/en/stable/ or any other documentation that uses readthedocs theme

(The links I added in my original issue at astropy main repo were not copied)

Note that the sidebar in these pages stays as a viewer scrolls the content panel as opposed to astropy-sphinx-theme behaviour where it scrolls with the content panel, quickly becoming just an empty div as long as content is longer than sidebar content.

Here is a small javascript library that shows demo as well: https://abouolia.github.io/sticky-sidebar/

In fact, I tried this library on astropy-sphinx-theme, and can get it working quickly but the way astropy-sphinx-theme is written, the sidebar divider that makes it collapsible is added after the document is ready in sidebar.js and it clashes with this naively implemented.

[kakirastern]

Hi @smoh

My apologies for the confusion. I think the original statement without the proper links attached can leave room for interpretation.

Yeah, I understand the complexity of your issue, as I faced it before while trying to tweak the original css code to add items to the topbar. As we are dealing with a customized sphinx theme that has some already established structure, the fix you tried before might not work so well in this context.

[kakirastern]

@smoh I think you might need something like the sticky_navigation option set to True in the html_theme_options of the conf.py file in the AstroPy repo for the TOC as described in https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html ... So this repo may not be what needs to be changed. You may need to open an issue or a PR there instead.

The site maintainer(s) may be in a better position to offer you guidance there.

[smoh]

The documentation you linked is for "ReadTheDocs" sphinx theme and is irrelevant.

I don't plan to spend significant time on hacking this. Just wanted to note that this would be nice to have.

[kakirastern]

Yeah, it might take days to figure it out on your own. But you can probably study the "ReadTheDocs" sphinx theme to make it work by modifying their sphinx theme and adapt to the AstroPy sphinx theme to make things work, so the link I provided is not totally irrelevant.

[rikvl]

PRs #23 and #24 are two attempts at fixing this issue, neither of them perfect:

In #23, the fix is implemented mostly in JavaScript. The behaviour is as expected (as far as I can tell), but the scrolling is often jittery.

In #24, the fix is implemented in CSS only. The scrolling is smooth, but the behaviour for a long ToC (which vertically overflows the element) is a bit different.

Only one of these two (if any) should be accepted.