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 https://github.com/pandas-dev/pydata-sphinx-theme/pull/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 ?

[choldgraf]

IMO we could just close this and refer to the other theme options that are out there (probably in particular the book theme, since it builds heavily on this theme's structure and style). My feeling is that we should focus our efforts on making this a great three-column layout theme, rather than trying to accommodate many different layouts. I'll hold off on closing this to see if others object though!

[kinow]

We are building the CWL User Guide with this theme, and at the moment we have the same issue, where our landing page has a blank/empty space in our sidebar. The search is useful (although I wouldn't mind if it was moved to the top bar as mentioned in linked discussions), but having our table of contents rendered on the left-sidebar would be better for us.

For now, I found the simplest way to achieve this—after looking at @choldgraf's example in #536 (thanks!)—to just pass the startdepth=0 in our sidebar HTML (in _templates/sidebar-nav-bs.html). We were already using sidebar-nav-bs.html to customize the Bootstrap CSS classes to hide the sidebar in small/mobile mode, related to #43.

<nav class="bd-links d-none d-md-block" id="bd-docs-nav" aria-label="{{ _('Main navigation') }}">
  <div class="bd-toc-item active">
    {{ generate_nav_html("sidebar",
                         startdepth=0,
                         show_nav_level=theme_show_nav_level|int,
                         maxdepth=theme_navigation_depth|int,
                         collapse=theme_collapse_navigation|tobool,
                         includehidden=True,
                         titles_only=True) }}
  </div>
</nav>

No matter the level the user is reading, the sidebar now displays the complete TOC from level 0, which so far looks good to us. But I believe others could try to customize it a bit if they prefer to have a different sidebar for the landing page, and for the other pages.

Thanks! -Bruno

[nathanrpage97]

A simple but cheesy work around I have is to add on the index page index.rst:

<meta http-equiv="refresh" content="0; url=all/index.html">

This will automatically redirect users to the nested docs all/index.rst. Change all/ to the desired nested name.

[12rambau]

IMO we could just close this and refer to the other theme options that are out there (probably in particular the book theme, since it builds heavily on this theme's structure and style). My feeling is that we should focus our efforts on making this a great three-column layout theme, rather than trying to accommodate many different layouts. I'll hold off on closing this to see if others object though!

Thank you all for your workarounds! As mentioned above, having the 2 behaviours within the theme would be too complicated so I'll close this issue.