Empty TOC in right sidebar

[tupui]

When the TOC is empty, the right sidebar is still present through bd-sidebar-secondary bd-toc

This is observed in SciPy. To build SciPy and the doc (build should take around 3 mins with 6 cores, then 5 mins for the doc itself):

# once you cloned my branch: https://github.com/scipy/scipy/pull/16660
# create an conda env to install everything
# don't try on windows as it will mostly fail.
mamba create env -f environment.yml
python dev.py doc -j 6  # number of cores

[choldgraf]

Can somebody please provide a minimal reproducible example or link? I worry that this won't get fixed if debugging requires building the entire scipy docs...

[drammock]

I've put in a PR to MNE-Python that should generate a working CircleCI site that demos this error. Will update here once the build is done.

[drammock]

Here is the rendered MNE-Python doc with the empty right column:

• homepage
• installation page

[choldgraf]

Diagnosis of what's going wrong

OK looking at the docs that @drammock shared, I think that this is the problem:

• We have two extra toc items enabled by default: edit-this-page, and sourcelink (ref). These are all added to theme_page_sidebar_items.
• In addition, we provide configuration flags to trigger this behavior on and off (ref).
• If people trigger edit-this-page or sourcelink to be False, then they won't show up, but their **template will still be in theme_page_sidebar_items. As a result, two empty <div>s will be created corresponding to the empty template of each.

What we can do to improve this

Short-term fix

First off, I think that @drammock and @tupui can solve their problem by defining:

html_theme_options = {
  ...
  "secondary_sidebar_items": ["page-toc"],
  ...
}

This should remove those empty <div> elements entirely.

Long-term fix

Ultimately, I think the behavior that we would want is:

• Setting any of the config for these features to False should also remove it from the secondary_sidebar_items list. Similar to what we do with the primary sidebar if there are no navigation entries to display.
• If there are no entries in the secondary-sidebar, then the whole sidebar should not show up at all, and allow extra space for the content.
• Either way, we need to document all of these more clearly!

If somebody wants to give a shot at the long-term fix, I'm happy to review!

[tupui]

I will try the work around tomorrow thanks!

[tupui]

I can confirm that it does fix the issue (and does not seem to have unwanted side effect for me), thanks! 😃

[drammock]

html_theme_options = {
  ...
  "page_sidebar_items": ["page-toc"],
  ...
}

agreed that this does fix things for MNE-Python docs too. I'll see if I can figure out the long-term fix.

[drammock]

Also since there's a very easy workaround (just one line change to conf.py) I'm comfortable removing the block-release tag on this one.