Option to have a (home) page with different layout (eg no left sidebar)

[jorisvandenbossche]

For the pandas docs, we now have this landing page with the latest version of the docs (https://pandas.pydata.org/pandas-docs/dev/index.html):

Which doesn't really look ideal. Some elements:

• The search bar in a for the rest empty sidebar looks a bit strange. However, putting the search bar somewhere else only on the home page might also be confusing ..
• Now we made the content of the main text limited, not a lot of space is used since both sidebars are empty. In this case, the main text could maybe take more space (and in this specific case, the card boxes also look a bit "squeezed" to me)

If we would have an option to make the content wider on such a page, how it would then work with alignment of the links in the navbar etc (which are now above the main content), is not fully clear though.

[choldgraf]

I think the big question is the search bar. It should be relatively straightforward to make the left navbar disappear if it is totally empty, but then the search bar would need to go somewhere...

[chrisjsewell]

As discussed in #192 personally I do prefer aspects of the RTD layout for the front-page, at least for the amount/depth of content in the AiiDA documentation:

You get a very clear understanding of the sites contents:

1. With the panels design (that I "borrowed" from @jorisvandenbossche thanks), you get a nice brief description of the goal/content of each section, and then
2. With the ToC you can quickly find/navigate to the page you are interested in, without having to go through an extra step of navigating to a particular section.

[choldgraf]

@chrisjsewell though if you don't want the topbar of the theme, then that's what either the "left-sidebar" version of the pydata theme (which needs development), or the sphinx-book-theme, would accomplish, no? Is there a reason you can't use one of those options, since they share much of the same CSS etc?

Or put another way, IMO the RTD theme and the pydata sphinx theme have fundamentally different structures, so they aren't meant as replacements of one another. The pydata theme is for more complex, multi-section content, more like a full-on website than a theme proper for a small package. The single-page version of the theme, or the sphinx-book-theme are more suited for smaller packages.

[chrisjsewell]

@choldgraf see some more musings in #192 (comment).
Eurgh neither feel quite ideal, we've gone with pydata: https://138-77234579-gh.circle-artifacts.com/0/html/index.html, but it would be ideal to fill all that blank left space, at least on the landing page, with the full ToC

[choldgraf]

at least on the landing page, with the full ToC

That's an interesting idea, and might be doable for just the landing page.

In the AIIDA case, it sounds like you don't want the top-bar at all then?

[mwaskom]

I'd prefer if this were configurable on a page-by-page basis. For example, in the seaborn docs, I'd want the example gallery to take up the full horizontal width of the page. Other gallery pages for visually-oriented packages may benefit from this too.

[jorisvandenbossche]

I think it should be possible with a sphinx "file metadata" (https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html#file-wide-metadata) to choose a different layout for a certain page.

For example, we could have a layout without left+right sidebar, so just the header/footer and a body that takes the full width, and then a way to select this, like putting

:page-layout: full-width

[jorisvandenbossche]

We actually already have an (undocumented) option to not show the right-side TOC on a certain page with :notoc:

[choldgraf]

using page metadata makes sense to me 👍

[jorisvandenbossche]

Some potentially relevant info:

• https://stackoverflow.com/questions/13209597/override-html-page-template-for-a-specific-sphinx-document
• https://www.sphinx-doc.org/en/master/extdev/appapi.html#event-html-page-context (this event can return the template name based on the context)