Fix extra whitespace in sidebars

[choldgraf]

This refactors some of our sidebar template logic in order to avoid having "empty but still present" sidebar items. It does so with the following steps:

• Adds a section to our HTML template event that handles removing templates that we know to be empty.
• Checks for specific configuration for the edit-this-page and show-sourcelink to remove these templates if the user has configuration to do so (even if the template is still part of the template list)
• Moves our "is the page toc empty?" check to this Python function rather than being part of the jinja HTML template.
• Fixes a doc that incorrectly said this was related to sphinx.ext.viewcode
• Moves the searchbox.html out of the secondary sidebar and instead to just above the article content. This way the presence of this button does not depend on their being a secondary sidebar. It also means there is not an "empty whitespace" in the sidebar because of the padding given to all toc-item elements. It will now show just above the page title.
• This means that on pages without the sourcelink/edit this page, and with no in-page TOC, the secondary sidebar will hide completely by default. closes Empty TOC in right sidebar #854 closes Extra vertical whitespace padding above h1 in theme v0.10.0 #955
• While I'm at it, add a check for whether globalcontext exists and only use it if so. closes Error in _overwrite_pygments_css: DirectoryHTMLBuilder' object has no attribute 'globalcontext' #1096

We could do something a little more clever, and actually try to render each template and manually check if it is empty. But I didn't do this because I was worried it'd be too computationally expensive. If others think it's not a big deal, I could try that (perhaps skipping our page-toc and site-toc templates). The code would be roughly:

rendered = app.builder.templates.render("TEMPLATENAME", context)
if len(rendered) == 0:
    # remove template

[choldgraf]

hmmm @drammock it seems that latest commit made the tests start to fail 🤔

[drammock]

hmmm @drammock it seems that latest commit made the tests start to fail thinking

pushed a commit that fixes it (locally at least, but should pass CIs too)

[12rambau]

I see the point of moving away the searchbox.html template from the secondary sidebar but I think it will be invisible for user where you display it now.

Use case:
I search the word "Customize logo link" in our doc and click on the first link (branding page). As the result is not on the first line of the page the "hide search result button" is simply invisible as it's on the top of the page.

What if instead we identify the status of the searchbox (displayed or not) and use a css selector to display (or not) the secodary sidebar. This behavior should be only triggered if the searchbox is the only item in it. This can be setup with an extra class to the secondary sidebar such as only-searchbox.

Advantage:

• make good use of your new python script to guess if it's a "only-searchbox" sidebar
• the button remain visible wherever you scroll
• nicer look (as the button was designed to be there in the first place)

what do you think ?

[choldgraf]

Two quick updates:

• I realized that there was another "ghost template" at the bottom of the primary sidebar, so I decided to go ahead and generalize the function to remove any empty template, rather than special-casing each one. This checks every single template, except for a few hard-coded ones that we know take longer to render. So build time shouldn't be affected. I also added a test.
• I'm not sure what you mean by What if instead we identify the status of the searchbox (displayed or not) and use a css selector to display (or not) the secodary sidebar. Do you mean identify it with JavaScript manually? The challenge with CSS is that you can't define a rule for a parent based on the selector for a child. Another concern I'd have with this is that when somebody clicked the button, it would suddenly make all of the content expand which might be jarring.

Another option is we could make the button floating in the bottom-right - then it's always visible but doesn't break the flow of the page at all...

[12rambau]

The challenge with CSS is that you can't define a rule for a parent based on the selector for a child.

damned, you're right. Ok then second suggestion: a customized btn (too make it look like a versionadded directive but with info type) and set it fixed on top of the article. As such we don't break the display by addign extra stuff on the right and we get access to the btn anywhere we scroll.

Another option is we could make the button floating in the bottom-right

This is were the RDT fly-out was and phone users were complaining a lot. Not sure setting anything there will make people happy

[choldgraf]

How about we do your suggestion here:

a customized btn (too make it look like a versionadded directive but with info type) and set it fixed on top of the article

but put it both above and below the article, so that a user has a higher chance of seeing it quickly. We might need to modify the JS to handle two buttons rather than one but that doesn't seem too tough.

[choldgraf]

Argh so we can't put it both above and below because the searchbox JavaScript is a sphinx-specific thing, not JS that we define.

So in the latest commit I tried something else: putting it in the primary sidebar at the top, rather than the secondary sidebar. My reasoning is that it is more common for the primary sidebar to be present than the secondary sidebar, and it is also visible anywhere, so this will make it easier to notice and use. This also puts it in the same place as other "control the site behavior" switches like the theme switcher.

Here's how that looks:

Another option is that we could actually make this an icon, and put it next to the search icon. e.g., an X icon that shows up next to the search icon.

[12rambau]

I like the idea but If you set it in the primary sidebar you will end up with the same problem as in #1092.
I started doing simple documentation recently using our theme and the primary sidebar is often removed (I have like 3 pages and basta): https://pygadm.readthedocs.io/en/stable/usage.html

What is clear is that making both the sidebars optionals is considerably reducing our options for extra information...
header navbar is indeed the only one always present but will people see the extra btn ?

[choldgraf]

Hmmm good point - how about we go with your original proposal but put it at the top of the page. I think that people will naturally scroll around a bit and will notice it there if we make the style noticeable. If people raise complaints that they can't find it, we can find another UX for it.

[choldgraf]

OK the latest commit moves the button back to the top of the article, it also makes it a little bit bigger and styles it similar to the sphinx-design buttons on this page: https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/web-components.html#badges-and-buttons. I made the button a little bit bigger than normal, so that it is a bit more noticeable. I figure it's not such a big deal because this button is rarely on pages and only after someone has explicitly searched for something. But happy to make it smaller if folks prefer.

Edit: now that I've looked at the GIF looping a few times...I'm thinking the button is too big...let me know if you agree :-)

Here's a GIF of the UX:

[12rambau]

I like the last itteration.

I don't know yet about the btn, I would say let's send it and see what folks have to say and we'll customize it in a follow up PR.

The most urgent thing here is to get rid of the secondary navbar !

[drammock]

❤️ I did not know this shorcut, I've been using --no-reuse-existing-virtualenvs which is so long to type that it hurts.