Consider using alabaster_jupyterhub for documentation

[choldgraf]

Hey all - in #126 I'm adding some updated content to the Sphinx site. I'm not touching any of the theming, design, etc since I don't want those kinds of questions to block improvements to the content.

I was wondering how folks think about using a different theme for the quantstack docs. The JupyterHub team has been maintaining a slightly modified version of Alabaster called Alabaster JupyterHub.

Here's an example repository that uses it. It's similar to the RTD theme, but has a couple extra features like a right within-page navbar, more minimalistic colorschemes, prev/next at the top and bottom, etc.

No worries if folks would rather not, but I wanted to throw it out there in case people were interested!

[maartenbreddels]

Great work on that PR!

However, I vote strongly against a non-default rtd theme. I think a non-default rtd theme is an unneeded cognitive burden for users. If you stick with the default, people directly recognize it. Any other theme and you have to think about what it is you are looking at. Even if a theme is better in some way, sticking to the default gives a much better UX I think (at least for me, and I know others agree).

[SylvainCorlay]

I agree with @maartenbreddels . Note that in early discussions about jupyter documentation, we also argued that Jupyter should stick to the readthedocs defaults, and improve it where it may not be as good as we would like, rather than maintaining our own theme.

[choldgraf]

Thanks for the comments - I totally agree about unnecessary forking of documentation themes.

Regarding @SylvainCorlay's point here:

Note that in early discussions about jupyter documentation, we also argued that Jupyter should stick to the readthedocs defaults, and improve it where it may not be as good as we would like, rather than maintaining our own theme.

That's precisely what alabaster_jupyterhub is trying to do - it's about 80 HTML template lines + a CSS file different from Alabaster. The biggest change is the "on this page" right sidebar, instead of embedding "on this page" links within the navigation to the left. Most other stuff is CSS to accommodate this.

The main reason it exists as a separate package is just because we were starting to copy/paste the same HTML template+CSS files in each jupyterhub repo (jupyterhub, repo2docker, binder, binderhub, z2jh, etc), and this was a way for us to propagate small theme changes to all of the repositories automatically.

To dig into this a little bit more: do you think you'd feel differently if alabaster_jupyterhub were instead a slight modification of the RTD theme rather than alabaster? (the main thing I prefer over default RTD is having within-page links to the right if the screen is wide enough)

[maartenbreddels]

(the main thing I prefer over default RTD is having within-page links to the right if the screen is wide enough)

I may like that actually, my main issue is that it isn't recognizable as a rtd page.

[choldgraf]

@maartenbreddels that's because, at the time, the JupyterHub projects were using Alabaster (https://alabaster.readthedocs.io/en/latest/index.html) and not the RTD theme, so I just began with Alabaster as a starting point instead. It would be really easy to modify the RTD to adopt the same behavior though.

[SylvainCorlay]

Gotcha.

To add more context, I recall that there were discussions about using Alabaster instead of the rtd theme for all jupyter projects, and there were arguments about Alabaster being better. However the look and feel of sphinx_rtd_theme is very easily identified and one immediately understands that they are looking at a package documentation and not another web site.

Besides the rtd theme shows the small ads that help fund readthedocs, so it is probably preferable to them that we use their theme if we are hosted on rtd.

[choldgraf]

Makes sense to me - I think those discussions happened before my time, I don't personally have strong opinions on RTD vs. Alabaster theme, though I do think the right sidebar is nice :-) I'm more opinionated about "all core jupyter repos should have the same theme, one day", but that's a discussion for another time.

@maartenbreddels you made me decide to scratch an itch. It looks like you could get right-sidebar behavior in the RTD theme using only CSS, which is pretty neat. For me, adding this CSS to the page:

/* Sidebar */
@media screen and (min-width: 1270px) {
    li.toctree-l1.current > ul {
        position: fixed;
        margin-left: 0px;
        overflow-y: auto;
        padding-left: 5px;
        border-left: 1px solid #767677;
        height: 95%;
        top: 70px;
        left: 1100px;
    }

    li.toctree-l1.current ul, li.toctree-l1.current li, li.toctree-l1.current a {
        background-color: transparent !important;
    }
}

/* Ensure the background is uniform color */
.wy-nav-content-wrap {
    background: #fcfcfc !important;
}

results in the following behavior:

Maybe the lab community would be interested in this?

[SylvainCorlay]

@choldgraf thanks for the proposed improvement.

As I am doing some triage, I suggest we split discussions on improving upon sphinx_rtd_theme into other issues, and close this.