Allow for a single-level version of this theme

[choldgraf]

For a few projects that I'm using, I'd like to use this project for its simplicity, style, and modernity. However, our documentation isn't complex enough that it warrants a topbar with sections. We really only need an alabaster-style single sidebar that behaves sensible (with an in-page TOC to the right).

I wonder if we could set up the templates such that we could easily swap between a "multi-level" and "single-level" approach

[jorisvandenbossche]

Yes, I have been thinking about adding multiple layouts (more simple) layouts that you can choose from, but that can share common building blocks in this project.

The alabaster-style single sidebar + in page TOC would become similar to a readthedocs+toc-sidebar from a layout point of view? (which would be useful to have!)

Next to the Alabaster-style layout, some other layout ideas:

• gitbook (https://docs.gitbook.com/) does something similar with a left sidebar for navigation and right sidebar for TOC, just with a top-bar to have the logo, but which scrolls away.
  (the gitbook docs itself have some "privacy", "about", etc links in the top bar, but I have seen projects using gitbook that don't have anything there)

• Something similar to the default bootstrap-sphinx-theme (http://ryan-roemer.github.io/sphinx-bootstrap-theme/README.html), i.e. only a topbar for between-page navigation (and not the left sidebar with secondary level). Eg seaborn (https://seaborn.pydata.org/) and numba (https://numba.pydata.org/numba-doc/latest/index.html) use this as well. And MNE-python uses a variation of this theme as well (https://mne.tools/stable/index.html)

• pkgdown in R gives something similar (https://pkgdown.r-lib.org/articles/pkgdown.html) with a top bar for page navigation, and then only a TOC sidebar

• Docsy: https://example.docsy.dev/docs/. They use the left sidebar for all documentation navigation, the links on the top bar are more for general website items (like "about") that gives pages with a different layout

• A very simple single page (single toc) site: https://drivendata.github.io/cookiecutter-data-science/

[choldgraf]

relevant to your gitbook comment, I'd love to use this theme for Jupyter Book (which draws inspiration heavily from GitBook). We are thinking about re-writing the backend for JupyterBook to use Sphinx, and in that case, it would be great if we used a theme that built off of a good foundation such as the pydata theme

[jorisvandenbossche]

I was just experimenting with a customized version for a small package, to do something alabaster-like.

This is the result for now: http://jorisvandenbossche.github.io/example-pandas-docs/contextily/index.html
(and the customizations that I needed to make to get that: https://github.com/darribas/contextily/pull/130, there are certainly still a lot of other things to improve)

We should certainly make this even simpler, or actually include this as option in this package?

[choldgraf]

Is this something that the sphinx-book-theme could be useful for as well? I think it acts well as a more "lightweight" version of the pydata theme:

https://sphinx-book-theme.readthedocs.io/en/latest/

I have been trying to upstream as much as possible into pydata-sphinx-theme...I would be happy to find a way to make this more generally useful for the community (already it is designed to be pretty modular, and doesn't "depend" on Jupyter Book)

[jorisvandenbossche]

I actually looked at sphinx-book-theme's code / layout as inspiration :) (I could actually also just have tried it out ..)

My feeling says that something basic like this would be nice to simply include here. I don't know how well it works, though, to include multiple possible layouts in a single package / single theme. But is has been on my mind for a longer time (see also the older posts in this issue) to provide a configurable layout in this theme.

I have been trying to upstream as much as possible into pydata-sphinx-theme...

And thanks a lot for that, and sorry that I have not always been up to speed to review this

[jorisvandenbossche]

Very concretely on this specific layout and jupyter-book-theme, some questions that come to my mind:

• What aspect of it is still "specific" to the book aspect in the jupyter-book-theme?
• Or, put it the other way, what would someone prefer to do differently when using it for a basic doc site?

For example, I suppose the download button at the top is maybe something book-specific (and the printing css), or the in-content-sidebar, or ... So those are still add-ons that sphinx-book-theme could provide, even if more of the layout specific things would be included here?

On the other hand, it's great that other packages start customizing this theme and depending on it, so it might also be fine to leaving it to another package to "specialize" in a different default layout.

[choldgraf]

I agree with you there are probably things in there that aren't useful for a generic pydata-style website. I don't know that those are things that would be problems for people, they just might not be as useful.

I agree with you that a "single page" version of this theme would be good as well...that's part of what #110 was setting the stage for. Maybe it is accomplishable by upstreaming more things from the sphinx-book-theme (e.g. the sidebar collapse animation?). I'd love to be able to have the sphinx-book-theme as lightweight as possible so that others can use the core features for their own purposes.

[choldgraf]

Just another note here that I think the sphinx-book-theme has evolved nicely as a single-page version of this theme. We've started using it for some of our smaller documentation sites as well. E.g. here's the markdown-it-py docs:

(link: https://markdown-it-py.readthedocs.io/en/latest/)

Throwing it out there to see if it could be used as a single-page alternative to this theme. There is still some upstreaming I want to do for the sphinx-book-theme into this one, but it would be good to keep the two themes connected w/ one another so they can benefit from each other's development.

If there are some awkward "book-like" features in there that don't make sense for a single-page docs site, I'd be friendly to removing them as defaults and having them configurable for people that want a book-like layout

[jpmckinney]

A lot of similar issues like #146, in addition to those mentioning this issue above. Can they be consolidated?

[12rambau]

We are now advertising Furo and sphinx-book for single-level documentation in index.rst, should we close this issue ?