Maximum width of the main body of the page

[jorisvandenbossche]

Currently there is not max width, resulting in too wide text of the main body of a documentation page on big screens.

[choldgraf]

One site to use for inspiration is the Tufte CSS demo site: https://edwardtufte.github.io/tufte-css/

For that site, the main content section maxes out at a width of 770px. Perhaps we can follow something close to this for the sphinx theme

Note that this can be relatively easily accomplished with something like:

nav#navbar-main, div.container-fluid, div.footer {
    max-width: 1000px;
    margin-left: auto;
    margin-right: auto;
}

We may also want to give the main content "div" its own ID (e.g. #main or something like that)

[TomAugspurger]

+1 to doing something here. I noticed this especially for tables with only a few columns.

https://dev.pandas.io/docs/user_guide/boolean.html. Or should the table issue be resolved with its own max-width / styling?

[hoetmaaiers]

I have prepared some proposals to improve the design in full width. Indeed limiting the body to a maximum width is a good idea.

1: Original fulll width view of theme. For reference.

2: Same setup, only applied a maximum width to the body container.

3: Same setup, but moving both navigation columns next to each other.

3.1: Also moving both navigation columns next to each other + rearranged some elements around.

• search the docs on top
• edit this page to the right, out of direct sight.

This gives room for the main content to focus on. I do think the arrangement of left nav en secondary left nav can be improved a little regarding whitespace, hierarchy and more.

4. This mockup puts focus on the selected content. The primary navigation is in place to quickly switch between elements. The secondary navigation is put on top in an interactive component.When scrolling the title updates just like it is already in place. Also when scrolling the ‘on this page’ box will be floating fixed on top.

Below this mockup is an example of the open closed mechanism.

Open / closed on page navigation component:

[choldgraf]

Looks nice! A few quick thoughts:

• In some of those the search box is showing up in the top-bar. This should be configurable, I know many projects that have a lot of top-level sections and no horizontal space in the top-bar.
• In my mind, this would center the page in the middle, as opposed to left-justifying the page. Maybe a personal thing, but I don't notice whitespace as much when it is equal on both side, but notice it more when it is all to one side. Also, on super wide screens I feel like the content should always be in the middle of the screen...if things are left-justified they may still be off to the left of the screen.
• Is there a reason to show the in-page navigation on the left side of the content? That feels like a departure from convention for similar interfaces around reading documents (it's quite common for the in-page TOC to be on the right, so I feel like putting it on the left would add cognitive burden to users)

[jorisvandenbossche]

Thanks for the screenshots!

Personally (but yeah, I also developed the initial version .. ;)), I like the one that keeps the layout as it is now (with TOC sidebar on the right) the most. I agree with @choldgraf that having this on the right seems a common thing to do.

I think the collapsible navigation component for the TOC would still be useful for smaller screens, where the TOC sidebar doesn't fit (right now, it simply disappears, but it could go into such a collapsible TOC). In general, for a "focus mode", it might also be interesting to have a switch to hide/show the TOC sidebar (eg docker has this (icon in top right corner), or bookdown (but then for the left sidebar))

[choldgraf]

@jorisvandenbossche I use a within-page topbar to keep a placeholder for the table of contents, so that it only shows up when the screen is wide enough, but when the screen is narrow users can hover (or click) over the "toc" button and it'll show, e.g.:

(also see the arrow for the left across-pages navigation collapse. a lot of users of jupyter book like that 👍

[jorisvandenbossche]

In case we keep the 3-bar layout (topbar, left + right sidebar with central body content), I think the main question becomes how to align this content on the screen (what @choldgraf mentions about centering vs left-justifying).

Just putting some other examples here of different options:

---

Readthedocs (https://docs.readthedocs.io/en/stable/index.html)

-> they left-justify everything (but don't have a separate left TOC sidebar), resulting in a lot of white space at one side of the screen (or grey space here ;)). I think this is what @choldgraf mentioned above about noticing whitespace more if it is all on one side.

Some projects using readthedocs therefore also customize it to put the content in the middle, see eg https://xtensor.readthedocs.io/en/latest/

---

Similar to how xtensor centers the content with readtheocs, another example of this:

Elixir docs (https://hexdocs.pm/elixir/library-guidelines.html#getting-started)

-> they center the main text, but keep the left sidebar left-aligned

---

Docker (https://docs.docker.com/engine/docker-overview/)

-> they left-justify the text body, but keep the TOC sidebar right-justified (and so no longer directly next to the text). Although it is left-justified, the amount of "whitespace in the middle of the screen" is still somewhat limited (at least on my screen) because the width of the main text is still relatively big.

---

Git book, eg Metaflow docs (https://docs.metaflow.org/introduction/what-is-metaflow) or tiledb (https://docs.tiledb.com/main/use-cases/dataframes)

-> they center the main text content together with left and right sidebar next to it, leaving the whitespace fully on the right and on the left

---

Plotly (https://plot.ly/python/plotly-express/#maps)

-> similar as the one above in that they center the content + sidebar together (but they only have one sidebar)

---

Tensorflow (https://www.tensorflow.org/guide/keras/overview)

-> the left sidebar is left-justified, and then I think the main text body is centered with the right TOC sidebar put next to the text (but not taken into account for centering). But would need to look at the exact number of pixels or the css to be sure :)

Other example of the same concept (another google site, https://developers.google.com/protocol-buffers/docs/pythontutorial):

---

Let's also show the other deep learning framework to stay neutral :)

https://pytorch.org/docs/stable/notes/autograd.html

-> I thought this started as a readthedocs fork (but nowadays it is less visible, or it changed). So everything is also left-justified, but because everything is quite wide, the whitespace on the right annoys me not as much here.

---

Sparklyr / RStudio (https://spark.rstudio.com/dplyr/)

-> they left-justify the left-sidebar + content, but keep the TOC sidebar right-justified (BTW, I like here how the TOC sidebar is really subtle: it's there if you want to use it / look at it, but it also doesn't really annoy otherwise) This is similar to the docker example, but the whitespace is more apparent because the width of the content is smaller.

---

So far the doc sites I gathered over the year thinking about a better theme .. Sorry for the long post :)

[jorisvandenbossche]

And additional issue is: depending on how the content is aligned, the alignment of the items in the top header bar could also be under discussion.

[hoetmaaiers]

To me the Gitbook / Metaflow alignment is interesting. In this layout the navigation (both left/right) stays close to the content it is describing.

Also center-aligning the top header bar might feel good in combination with centering the content.

[choldgraf]

gitbook/metaflow is exactly what I'd like :-)

Also interesting to see they adopted the same 'edit on github' pattern in the right TOC bar that we did!

[jorisvandenbossche]

Yes, for me exploring the gitbook/metaflow layout sounds certainly good!

One possible counter point of having the content centered, but not the sidebars, is that it can give more "focus" on the main content. Eg with bookdown:

(but they have only one sidebar, so less bars anyway)

But I suppose that as long as we don't make the sidebars look "too heavy", that's no problem. And we should maybe rather implement a "focus mode" with a toggle to hide the sidebars, if that is something that people want. BTW, I just noticed that with bookdown, this toggle is integrated into the firefox bar: "Toggle reader view"

[choldgraf]

Either one is fine with me, so long as the content is centered (and ideally so that the right-page TOC stays with the content). Basically everything that is "about the current page" should be bundled together and centered, and other stuff I think is OK to be floating.

[hoetmaaiers]

I do agree on keeping everything 'about the current page' close to the main content. I will provide a mockup with the content centered before heading over to coding it.

[hoetmaaiers]

This is a mockup with the content centered. Also the search input is moved to the header. Also some more white space to is provided by rearanging some elements.

[choldgraf]

I think it looks quite nice!

A few questions:

• What happens w/ the search bar when we have lots of top-level headers, or long headers?
• How does the TOC behave on smaller screens?
• That "edit this page" button looks like it might be an extension point for new kinds of buttons, is that the intent? (I'd like something like this)

[hoetmaaiers]

• What happens w/ the search bar when we have lots of top-level headers, or long headers?

This does limit the amount / width of top level navigation items. It might be reason to move the search component into the left navigation column. A solution to keep the search component in the top navigation would be to reduce the component to a single search icon and only activate the input element on click or hover. A search icon is pretty universally recognised I think?

• How does the TOC behave on smaller screens?

At this moment the TOC will disappear at a certain viewport width (<1200). In a first iteration I would keep this. As a next improvement a TOC component hovering on page can be nice to have. Example:

• That "edit this page" button looks like it might be an extension point for new kinds of buttons, is that the intent? (I'd like something like this)

This is not intentional. What kind of extension point are you thinking about?

[hoetmaaiers]

Do we agree on the full centered version based on Gitbook / Metaflow working towards my latest mockup?

[choldgraf]

Yep, I think your latest mockup looks nice, +1 from me 👍

Re: the extension point thing, it just seems like that's a slot that other kinds of buttons could be added to if they existed. Maybe expanding out horizontally? Either way, I think that's a different issue to tackle :-)

One thing though: I would make the search bar configurable to either be in the top-bar, or in the sidebar. Some of our docs are already close to maxing out our top-bar space

[hoetmaaiers]

Ok, thank you for the thoughts. I suggest to keep the search bar to the left as it is now. Then later add in as a separate feature making the search bars position configurable?

[choldgraf]

+1 from me on that, I think that search bar location is orthogonal to content centering - I'll open an issue about the search bar

[jorisvandenbossche]

Need to go through the above discussion, but +1 on going forward with a gitbook/metaflow like style and the mockup!

[chrisjsewell]

This may be related, but using this theme on mobile, I can’t select the menu button. As you can see below, it looks like it is because for some reason the logo is overlapping it (the selection was made with a double tap)

[jorisvandenbossche]

This may be related, but using this theme on mobile, I can’t select the menu button.

@chrisjsewell sorry for the late reply. I indeed also see that issue on https://jupyter-cache.readthedocs.io/en/latest/#, but on https://pydata-sphinx-theme.readthedocs.io/en/latest/ If you still have it, can you open a separate issue about it?

[jorisvandenbossche]

Closed by https://github.com/pandas-dev/pydata-sphinx-theme/pull/134

[jorisvandenbossche]

@chrisjsewell actually, I remember now we had a similar issue with pandas, which in the end turned out to be related to our usage of nbsphinx, and related to the usage of requirejs (see https://github.com/pandas-dev/pydata-sphinx-theme/issues/25, and https://github.com/pandas-dev/pydata-sphinx-theme/issues/30 for the more general issue). It might be something similar?