Use the Sphinx sidebars function

[choldgraf]

We've had a few requests for more flexible sidebar layouts in the theme (e.g. #146 #234). Currently we are hard-coding the sidebar content, but we could make the sidebars extensible by piggy-backing on Sphinx's sidebar templating functionality:

https://www.sphinx-doc.org/en/master/templating.html?highlight=sidebar

I think we could make the default behavior the same by defining our own list of html_sidebars (https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars). However, users would then be able to over-ride this behavior if they wish, which would give more customizability.

This would make it easier for people to choose the sidebar they wish (while preserving our current behavior). I came across this behavior when looking into using the pydata theme with the ablog extension which lets you put author information into the sidebar.

I think this change would be something like:

• Add the following to our docs-sidebar.html template:

  {%- for sidebartemplate in sidebars %}
  {%- include sidebartemplate %}
  {%- endfor %}
  

  This would add whatever html_sidebars points to

• Set the default value of html_sidebars to None for this theme (Sphinx by default makes it load a few things)

That way, if people set html_sidebars, it'd show up in our sidebar.

We could also optionally package our search code as well as the bootstrap navigation code as templates that are included in the sidebar like anything else.

[CAM-Gerlach]

We added customizable sidebar support to our downstream fork in spyder-ide#33 , but I'm not sure the implementation was optimal—it uses the html_sidebars config variable but we inject the included templates into our existing sidebar, instead of using the actual Sphinx function or doing so for the whole sidebar, which (I assume) was simpler to implement into the existing theme but does limit customizability and doesn't seem to exactly be a best practice...

[choldgraf]

Note - I figured out an (I think) easier way to do this and I updated the top-level comment with some new ideas! I won't have the time to implement this (I'm on paternity leave) but I don't think it should be too complex and I'm happy to review a PR!

[choldgraf]

I have an implementation of the PR in #248 demoed at my new personal blog - decided to push the limit and see if I could re-create my old jekyll blog with Sphinx, and it was surprisingly easy!

https://predictablynoisy.com/

(note I'm using my fork of this theme since #248 isn't merged yet)

[jorisvandenbossche]

Wow, that's a cool usage of the sidebars! Also for the blog page ;)