✨ NEW: hide sidebar + navbar_align options

[choldgraf]

This adds support for hiding sidebars on some page using html_sidebars. It does a few things to make this work:

• Using html_sidebars, check for whether any sidebar items exist on a page, and if not, it shrinks and hides the sidebar.
• Grows the content by 1-2 columns when there is no sidebar
• Sets our navbar links to snap to the left so that no sidebars doesn't result in weird offsets

👆 That last one in particular may be worth discussing, but IMO it is a more robust solution than trying to make the navbar links line up with the page content. The reason I did this is because unless we keep the navbar items snapped to the left (or right) side of the page, any change in content width is going to be jarring for the user since they'll expect them to line up

And for our docs:

• sets the search bar for our docs to be in the top-right so that it isn't hidden on a page w/ no sidebar.
• sets the sidebar of the index page to hidden

Would love feedback on whether people think this is a good solution

New home page w/o sidebar on index:

Old home page with sidebar on index:

Partially addresses #262 #146

another option here would be to use a specific config like nosidebar for certain pages, rather than inferring it from the html_sidebars config (as @mwaskom suggested)...I'd be fine with that approach too but wanted to get this up here to look at

[choldgraf]

Can I please get some comments on this? Maybe either @hoetmaaiers or @jorisvandenbossche ? I just rebased and lost like 30 minutes trying to figure out how to re-build webpack and not generate more conflicts, so I would really like to either close this if people don't want it, or make modifications and get it merged so that I don't have to keep dealing with conflicts...

If folks are unhappy with the topbar behavior change, I can make it configurable for the user, but IMO it looks weirder to have the topbar mis-aligned from the text and in the middle if there is no sidebar, vs. just having the topbar items snap to the left all the time

(note, there are really only a few files changed here, the 66 files changed are because a bunch of packages updated when I ran the pre-commit)

[choldgraf]

here we make the topbar items position to the left, instead of being centered in the middle of the topbar

[choldgraf]

setting the main content to just col as I believe this will make it grow to fill up available space around it, rather than explicitly defining its size.

[jorisvandenbossche]

It seems that this change is causing the problem on https://pydata-sphinx-theme--263.org.readthedocs.build/en/263/demo/demo.html
I suppose there is some content on that page that is larger, and causes the main text column to be wider if it is not constrained to a max size, and then causing the right toc sidebar to have no space anymore to appear on the side

[jorisvandenbossche]

@choldgraf taking a look now (and thanks for working on this!)

Hmm, if the dev setup with webpack keeps giving you headaches, we need to reconsider it (I don't fully understand what went wrong in this case, for me it mostly works smoothly, but it seems you updated the versions of the vendored assets (fonts, fontawesome)).

Generally it looks like a nice and clean solution to have the "no-sidebar" option. I am not yet fully convinced about the alignment of the links in the navbar, so if we could leave that for a separate PR that might be good (or configurable? although that might be hard). Will try to give some more input about that on the issue.

Looking at the preview docs, I notice a few issues:

• On https://pydata-sphinx-theme--263.org.readthedocs.build/en/263/demo/demo.html, the toc sidebar is messed up (it is shown in the left instead of right sidebar, fully at the bottom of the page). Not fully sure if it's a glitch with the preview, or actually caused by the changes in this PR (it also doesn't consistently happen on all pages)
• Due to the search box in the navbar, the height increased a bit (there is some padding around the searchbox div, that might need to be reduced for having it in the navbar). This also relates to BUG: anchor links hidden by header navbar when this has a different height #258 (which @hoetmaaiers is looking into)
• If the search box is not present, we might need to add some extra margin in the left sidebar (or in general add it, and remove some padding of the searchbox). For example here https://pydata-sphinx-theme--263.org.readthedocs.build/en/263/contributing.html we could use some more space above the content in the sidebar.

another option here would be to use a specific config like nosidebar for certain pages, rather than inferring it from the html_sidebars config

Do you know if it would be possible in sphinx to update this html_sidebars config when processing a given page based on such a nosidebar flag?
(certainly doesn't need to be done here, to be clear)

[jorisvandenbossche]

Do you know if it would be possible in sphinx to update this html_sidebars config when processing a given page based on such a nosidebar flag?

I suppose that if we want a nosidebar flag to also work, it could be done by changing the check {% if sidebars %} in the jinja template to something like {% if sidebars and not (meta is not none and 'nosidebar' in meta)%}
(but it's also providing two ways to do the same thing .. so not necessarily needed)

[choldgraf]

@jorisvandenbossche thanks for the review! A couple responses:

On pydata-sphinx-theme--263.org.readthedocs.build/en/263/demo/demo.html, the toc sidebar is messed up (it is shown in the left instead of right sidebar, fully at the bottom of the page). Not fully sure if it's a glitch with the preview, or actually caused by the changes in this PR (it also doesn't consistently happen on all pages)

good catch, I think this is actually related to using col in the main content. I will revert that and go back to explicitly defining the width.

I am not yet fully convinced about the alignment of the links in the navbar, so if we could leave that for a separate PR that might be good (or configurable? although that might be hard).

Lemme see how much work it'd be to make it configurable. It may not be too bad. Something like left_justify_navbar_links = False by default?

Due to the search box in the navbar, the height increased a bit (there is some padding around the searchbox div, that might need to be reduced for having it in the navbar). This also relates to #258 (which @hoetmaaiers is looking into)

Since that issue is not related to this PR and is more about the pydata theme docs themselves, how about I just move the search bar back to its normal position, and then I'll choose a page deeper in the docs where we can demo the "no sidebars" option rather than having it be the landing page. When we fix #258 then we can move the docs search bar to the navbar if we wish.

If the search box is not present, we might need to add some extra margin in the left sidebar (or in general add it, and remove some padding of the searchbox). For example here pydata-sphinx-theme--263.org.readthedocs.build/en/263/contributing.html we could use some more space above the content in the sidebar.

I will play around with this and try to get it to a nicer-looking default.

(but it's also providing two ways to do the same thing .. so not necessarily needed)

Yeah this was my feeling too. How about we start off with just using html_sidebars, since that's what most Sphinx sites use, and we can experiment with page-level metadata later on. That work?

[jorisvandenbossche]

How about we start off with just using html_sidebars, since that's what most Sphinx sites use, and we can experiment with page-level metadata later on. That work?

Certainly!

[choldgraf]

@jorisvandenbossche take a look at the latest push and see if that fixes things up. I believe that I addressed the comments that you gave.

This is the new page w/ no sidebar: https://pydata-sphinx-theme--263.org.readthedocs.build/en/263/changelog.html

And just to confirm, this page now works: https://pydata-sphinx-theme--263.org.readthedocs.build/en/263/demo/demo.html

[choldgraf]

OK @jorisvandenbossche - I've applied the patch you recommended and it worked! Also had to rebase to avoid a merge conflict with the hashes. I think this is ready to go if you're 👍 on the changes.

[choldgraf]

I take it back! Need to figure out one bug on the sidebar width

[choldgraf]

OK fixed - now it's ready for review and/or merge. You can demo here: https://pydata-sphinx-theme--263.org.readthedocs.build/en/263/changelog.html

(sorry for the noise @jorisvandenbossche )

[choldgraf]

@mwaskom it is how you configure the sidebars for any pages, including choosing particular components for the sidebar on subsets of pages, or removing it entirely in some cases.

html_sidebars is a core sphinx feature: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars

so if you do:

html_sidebars = {
  "page1": ["thing1.html", "thing2.html"],
  "section1/*": ["thing2.html"],
  "page3": [],
}

then the default sidebar components will show up on all pages except page1, page3, and all sub-pages within section1/, while the components specified here would show up on page1 and section1/*, and page3 would have no sidebar.

[jorisvandenbossche]

@choldgraf thanks for the updates! Playing around a bit with the demo docs looks good now

Lemme see how much work it'd be to make it configurable. It may not be too bad. Something like left_justify_navbar_links = False by default?

The options looks fine. I am only thinking about the type of value, which is now a boolean, and thus only leaves two options. Maybe something like navbar_alignment="left"|"content" is more robust if we also want to add a "right" option?

[choldgraf]

Hmmm - I don't have strong opinions on bool vs. left/content...I'd be happy to go with that if you think it's better

[hoetmaaiers]

Other then the suggestion to rework navbar_alignment to a string for extensibility, I have no other remarks.

[choldgraf]

OK so taking the feedback of @jorisvandenbossche and @hoetmaaiers , the config is now called navbar_align and can take 3 strings: left, content, and right. I re-worked the Jinja logic to use a Python function so that it's not too confusing to understand.

Here's what navbar_align="right" looks like:

[mwaskom]

Seemed pretty easy to get working, and did what I expected it to. The seaborn docs have some other aspects that render poorly with (at least the default config of) the pydata theme, but this one was a big hurdle. 👍

[choldgraf]

@mwaskom I'm curious what are the other places where the pydata theme doesn't work properly! (maybe in a different issue?)

[mwaskom]

Sure, but I feel like I should put in at least a minimum amount of effort to figure out whether it’s just a config setting that I can change :)

Seaborn docs also do a lot of bespoke html fiddling on top of the current Sphinx theme, and not at all in a principled or well-implemented way, so...

[jorisvandenbossche]

Thanks for the update!

[jorisvandenbossche]

@mwaskom any additional feedback / feature requests to get it working as you want with seaborn is very welcome!

[choldgraf]

wohoo! 🎉

[CodeCox]

@choldgraf There seems to be a minor typo in the configuration documentation:

   "navbar_align_with_content": "left"

should read:

   "navbar_align": "left"

occurs 3x ie. this config key is shown incorrectly for each of the three values.

(Apologies if this comment is in the wrong place but this has not been officialy released yet therefore I did not want to raise an issue.)

[choldgraf]

ah yes I believe you are right @CodeCox ! Wanna make a docs PR to change it? I'm happy to review

[CodeCox]

@choldgraf Yes, I'm happy to give it a shot in the next few days!

It's a trivial change but I need to figure out the PR process for this repository. It will be good preporatory learning for me.

(The code for this PR has not yet been officially released but the related doc is already live - so there is already a disjoint because of this disparity!)

[choldgraf]

I don't think here's a giant problem, but we should definitely fix soonish. No hurries and I am happy to help if you hit issues 👍