Refactor our HTML to be a bit more sensible

[choldgraf]

Problem description

In building the theme there are a few places where we have taken shortcuts and generally not tied the HTML / CSS structure to best practices. Originally this was done to speed things up, but we should start doing refactors to improve this structure in order to make the site more maintainable in the future. This will hopefully reduce unexpected CSS behavior and make it easier for folks to grok what is going on.

There are likely a few different places that need work, so we can use this issue as a catch-all for some of the bigger pieces. I'll list the stuff I know of right now that should get re-addressed.

Tasks and updates

A few major issues to tackle:

• Switch our build system to use the sphinx-theme-builder #417
• ENH: Sphinx-basic-ng as the base instead of pydata-sphinx-theme #456
• ENH: Support docutils 0.17.1 #392 - this will give us more "semantic" elements within the article itself
• get semantic tagging / structure correct - we are using some semantic elements incorrectly
  • <main> has some UI elements on it, whereas I believe it is supposed to only contain the page content)
  • Our left and right sidebars could be <asides>
• increase our whitespace around elements - potentially changing behavior at different breakpoints (e.g. visibility of TOC), see Left ToC too narrow for nested sections and left body margin too small #459
• make our the right TOC a top-level item - currently the right TOC lives inside the topbar div. This makes it more difficult to style because of the nesting. It should be a sibling of our content container.
• remove the use of fixed in the topbar
  we are using a fixed class for our topbar, even though really this should be done with a sticky class. This is forcing us to do some hacks with a "whitespace div" (.bd-topbar-whitespace) to force the in-page topbar to be aligned with the content.

[choldgraf]

OK I think that we have resolved the bulk of this one, and we have issues to track the remaining items (specifically, executablebooks/meta#576 for the basic-ng switch). We've made some nice incremental progress that will make it easier to make the switch to basic-ng if we like!