[WIP] REFACTOR: Re-work HTML structure and CSS

docs/content-blocks.md

@@ -179,16 +179,6 @@ We can reference the figure with {ref}`myfig4`. Or a numbered reference like
 You can configure figures to use the margin for captions.
 Here is a figure with a caption to the right.
 
-```{figure} images/cool.jpg
----
-width: 60%
-figclass: margin-caption
-alt: My figure text
-name: myfig5
----
-And here is my figure caption, if you look to the left, you can see that COOL is in big red letters. But you probably already noticed that, really I am just taking up space to see how the margin caption looks like when it is really long :-).
-```
-
 And the text that produced it:
 
 ````

setup.py

@@ -29,7 +29,7 @@
     packages=find_packages(),
     install_requires=[
         "beautifulsoup4>=4.6.1,<5",
-        "docutils>=0.15,<0.17",
+        "docutils>=0.15",
         'importlib-resources>=3.0,<3.5; python_version < "3.7"',
         "pydata-sphinx-theme~=0.7.2",
         "pyyaml",

sphinx_book_theme/footer.html

@@ -1,22 +1,24 @@
-<footer class="footer">
-  <p>
-    {% if author %}
-      {{ translate('By') }} {{ author }}<br/>
-    {% endif %}
-    {%- if show_copyright %}
-      {%- if hasdoc('copyright') %}
-        {% trans prefix=translate('Copyright'), path=pathto('copyright'), copyright=copyright|e %}&copy; <a href="{{ path }}">{{ prefix }}</a> {{ copyright }}.{% endtrans %}<br/>
-      {%- else %}
-        {% trans prefix=translate('Copyright'), copyright=copyright|e %}&copy; {{ prefix }} {{ copyright }}.{% endtrans %}<br/>
+<div class="row footer-row">
+  <footer class="col footer">
+    <p>
+      {% if author %}
+        {{ translate('By') }} {{ author }}<br/>
+      {% endif %}
+      {%- if show_copyright %}
+        {%- if hasdoc('copyright') %}
+          {% trans prefix=translate('Copyright'), path=pathto('copyright'), copyright=copyright|e %}&copy; <a href="{{ path }}">{{ prefix }}</a> {{ copyright }}.{% endtrans %}<br/>
+        {%- else %}
+          {% trans prefix=translate('Copyright'), copyright=copyright|e %}&copy; {{ prefix }} {{ copyright }}.{% endtrans %}<br/>
+        {%- endif %}
       {%- endif %}
-    {%- endif %}
-    {%- if last_updated %}
-      {% trans prefix=translate('Last updated on'), last_updated=last_updated|e %}{{ prefix }} {{ last_updated }}.{% endtrans %}<br/>
-    {%- endif %}
-    {%- if theme_extra_footer %}
-      <div class="extra_footer">
-        {{ theme_extra_footer }}
-      </div>
-    {%- endif %}
-  </p>
-</footer>
+      {%- if last_updated %}
+        {% trans prefix=translate('Last updated on'), last_updated=last_updated|e %}{{ prefix }} {{ last_updated }}.{% endtrans %}<br/>
+      {%- endif %}
+      {%- if theme_extra_footer %}
+        <div class="extra_footer">
+          {{ theme_extra_footer }}
+        </div>
+      {%- endif %}
+    </p>
+  </footer>
+</div>

sphinx_book_theme/layout.html

@@ -1,34 +1,34 @@
 {% extends "pydata_sphinx_theme/layout.html" %}
 
 {% set is_single_page = (theme_single_page == True) or (theme_single_page == "True") %}
-{% if is_single_page %}
-    {%- set sidebar_width_class = "col-md-2" %}
-{% else %}
-    {%- set sidebar_width_class = "col-md-3" %}
-{% endif %}
 
 <!-- Docs TOC is "d-none d-xl-block col-xl-2" -->
 {% block docs_sidebar %}
+<!-- An invisible pixel that we watch to see if we've scrolled. -->
+<div class="sbt-scroll-pixel-helper"></div>
 <!-- Checkboxes to toggle the left sidebar -->
 <input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation" aria-label="Toggle navigation sidebar">
-<label class="overlay" for="__navigation">
+<label class="overlay overlay-navbar" for="__navigation">
     <div class="visually-hidden">Toggle navigation sidebar</div>
 </label>
-<div class="col-12 {{ sidebar_width_class }} bd-sidebar site-navigation {% if is_single_page %} single-page{% endif %}" id="site-navigation">
+<!-- Checkboxes to toggle the in-page toc -->
+<input type="checkbox" class="sidebar-toggle" name="__page-toc" id="__page-toc" aria-label="Toggle in-page Table of Contents">
+<label class="overlay overlay-pagetoc" for="__page-toc">
+    <div class="visually-hidden">Toggle in-page Table of Contents</div>
+</label>
+<div class="pl-4 pr-3 bd-sidebar site-navigation {% if is_single_page %} single-page{% endif %}" id="site-navigation">
     {% if not is_single_page %}
         {% include "sidebar.html" %}
     {%- endif %}
 </div>
 {% endblock %}
 
 {% block docs_main %}
-<!-- This is an invisible pixel that we watch to see if we've scrolled. -->
-<div class="sbt-scroll-pixel-helper"></div>
-<main class="col py-md-3 pl-md-4 bd-content overflow-auto" role="main">
+<div class="col py-0 content-container">
     {% block docs_body %}
     {% include "topbar.html" %}
-    <div id="main-content" class="row">
-        <div class="col-12 col-md-9 pl-md-3 pr-md-0">
+    <div class="row content-row">
+        <div class="col pl-md-3 pl-lg-5 content-container">
             <!-- Table of contents that is only displayed when printing the page -->
             <div id="jb-print-docs-body" class="onlyprint">
                 <h1>{{ pagetitle }}</h1>
@@ -47,14 +47,16 @@ <h2> {{ translate(theme_toc_title) }} </h2>
                     </div>
                 </div>
             </div>
-            {{ super() }}
+            <main id="main-content" role="main">
+                {{ super() }}
+            </main>
             {% if theme_show_prev_next %}
                 {% include "_templates/prev-next.html" %}
             {% endif %}
         </div>
     </div>
-    {% endblock %}
     {%- include "footer.html" %}
+    {% endblock %}
 </main>
 {% endblock %}
 

sphinx_book_theme/theme.conf

@@ -3,7 +3,7 @@
 inherit = pydata_sphinx_theme
 pygments_style = tango
 sidebars = sidebar-logo.html, search-field.html, sbt-sidebar-nav.html, sbt-sidebar-footer.html
-stylesheet = sphinx-book-theme.css?digest=84ace793992934648b4de8eed757e5a2
+stylesheet = sphinx-book-theme.css?digest=8f8abae31615424de2a26d990b65e7a9
 
 [options]
 single_page = False

sphinx_book_theme/topbar.html

@@ -1,33 +1,34 @@
-<div class="topbar container-xl fixed-top">
-    <div class="topbar-contents row">
-        <div class="col-12 col-md-3 bd-topbar-whitespace site-navigation show"></div>
-        <div class="col pl-md-4 topbar-main">
-            <div class="topbar-left">
-                {% if theme_single_page != True %}
-                <label class="nav-toggle-button" for="__navigation">
-                    <div class="visually-hidden">{{ translate('Toggle navigation') }}</div>
-                    <i class="fas fa-bars"></i>
-                </label>
-                {% endif %}
-            </div>
-            {% include "topbar/download.html" %}
-            {% include "topbar/repobuttons.html" %}
-            {% include "topbar/fullscreen.html" %}
+{# To trigger whether the TOC and its button show up #}
+{% set page_toc = generate_toc_html() %}
+
+<div class="topbar row sticky-top">
+    <div class="col py-1 d-flex topbar-main">
+        <div class="topbar-left">
+            {% if theme_single_page != True %}
+            <label class="nav-toggle-button" for="__navigation">
+                <div class="visually-hidden">{{ translate('Toggle navigation') }}</div>
+                <i class="fas fa-bars"></i>
+            </label>
+            {% endif %}
+        </div>
+        <div class="topbar-right">
             {% include "topbar/launchbuttons.html" %}
+            {% include "topbar/fullscreen.html" %}
+            {% include "topbar/repobuttons.html" %}
+            {% include "topbar/download.html" %}
+            {% if page_toc %}{% include "topbar/toc-button.html" %}{% endif %}
         </div>
+    </div>
 
-        <!-- Table of contents -->
-        <div class="d-none d-md-block col-md-2 bd-toc show noprint">
-            {% set page_toc = generate_toc_html() %}
-
-            {%- if page_toc | length >= 1 %}
-            <div class="tocsection onthispage pt-5 pb-3">
-                <i class="fas fa-list"></i> {{ translate(theme_toc_title) }}
-            </div>
-            <nav id="bd-toc-nav" aria-label="Page">
-                {{ page_toc }}
-            </nav>
-            {%- endif %}
+    <!-- Table of contents -->
+    <div class="d-block col-md-3 bd-toc show noprint">
+        {%- if page_toc | length >= 1 %}
+        <div class="tocsection onthispage pt-5 pb-3">
+            <i class="fas fa-list"></i> {{ translate(theme_toc_title) }}
         </div>
+        <nav id="bd-toc-nav" aria-label="Page">
+            {{ page_toc }}
+        </nav>
+        {%- endif %}
     </div>
 </div>

sphinx_book_theme/topbar/toc-button.html

@@ -0,0 +1,4 @@
+<label class="d-block d-md-none nav-toggle-button topbarbtn" for="__page-toc">
+  <div class="visually-hidden">{{ translate('Toggle Table of Contents') }}</div>
+  <i class="fas fa-list"></i>
+</label>

src/js/sphinx-book-theme.js

@@ -98,7 +98,7 @@ var initTocHide = () => {
   marginSelector = []
   selectorClasses.forEach((ii) => {
     // Use three permutations of each class name because `tag_` and `_` used to be supported
-    marginSelector.push(...[`.${ii}`, `.tag_${ii}`, `.${ii.replace("-", "_")}`])
+    marginSelector.push(...[`.${ii}`, `.tag_${ii}`, `.${ii.replace("-", "_")}`, `.tag_${ii.replace("-", "_")}`])
   });
   document.querySelectorAll(marginSelector.join(", ")).forEach((ii) => {
     tocObserver.observe(ii);

src/scss/_footer.scss

@@ -2,9 +2,5 @@
 * Footer *
 *********************************************/
 footer {
-    padding-left: 0;
-
-    > div.container {
-        padding-left: 0;
-    }
+    font-size: var(--sbt-font-size-small-1);
 }

src/scss/_leftbar.scss

@@ -3,29 +3,36 @@
 *********************************************/
 #site-navigation  {
     height: 100vh !important;
-    width: $leftbar-width;
-    flex: auto;
+    width: $leftbar-width-wide;
+    font-size: var(--sbt-sidebar-font-size);
     top: 0px !important;
-    margin-left:0;
     overflow-y: auto;
     background: white;
-    transition: margin-left .2s ease 0s, opacity .2s ease 0s, visibility .2s ease 0s;
+    border-right: $border-thin;
+    transition: margin-left $animation-time ease 0s, opacity $animation-time ease 0s, visibility $animation-time ease 0s;
     z-index: 2000 !important;
 
     @include scrollbar-style();
+
     @media (max-width: $breakpoint-md) {
         position: fixed;
-        border-right: 1px solid rgba(0,0,0,.1);
+        width: $leftbar-width-mobile;
+        max-width: 300px;
     }
 
-    // Sidebar link color
     nav ul.nav {
+        // Sidebar link color
         li a, ul li a {
             color: $non-content-grey;
         }
         a:hover, li.active > a, li.active > a:hover {
             color: rgba(var(--pst-color-link), 1);;
         }
+
+        // Adjust padding to be a bit tighter
+        ul {
+            padding-left: 1rem;
+        }
     }
 
     h1.site-logo {
@@ -80,88 +87,3 @@ nav.bd-links {
     overflow-y: visible;
     max-height: none;
 }
-
-// Navbar and topbar sidebar padding should max at 300px
-@media (min-width: $breakpoint-md) {
-    .bd-sidebar {
-        max-width: 275px;
-    }
-}
-
-// Toggle the left sidebar
-@mixin sidebar-hidden {
-    ~ #site-navigation, ~ .bd-content .bd-topbar-whitespace {
-        visibility: hidden;
-        margin-left: -$leftbar-width;
-        opacity: 0;
-    }
-
-    ~ #site-navigation {
-        display: block;
-    }
-
-    // This should only be applied to the topbar-whitespace if we're on wide screen
-    @media (min-width: $breakpoint-md) {
-        ~ .bd-content .bd-topbar-whitespace {
-            display: block;
-        }
-    }
-}
-
-input#__navigation {
-    display: none;
-    position: absolute;
-
-    // On wide screens, checking will hide everything
-    @media (min-width: $breakpoint-md) {
-        &:checked {
-            @include sidebar-hidden;
-        }
-    }
-
-    // On narrow screens, *unchecking* will hide everything, so it's hidden by default
-    @media (max-width: $breakpoint-md) {
-        &:not(:checked) {
-            @include sidebar-hidden;
-        }
-    }
-}
-
-// The HTML is technically in the topbar, but we put SCSS rules here since it
-// behaves the same way as the sidebar
-// TODO: This should be refactored to have a more sensible structure
-.bd-topbar-whitespace {
-    width: $leftbar-width;
-    flex: auto;
-    transition: flex 0.2s ease 0s;
-    @media (max-width: $breakpoint-md) {
-        // Whitespace isn't needed on narrow screens since sidebar is separate
-        display: none;
-    }
-
-    // Navbar and topbar sidebar padding should max at 300px
-    @media (min-width: $breakpoint-md) {
-        max-width: 275px;
-    }
-}
-
-// Label at the top of the page
-label.overlay {
-    background-color: rgba(0,0,0,.54);
-    height: 0;
-    opacity: 0;
-    position: fixed;
-    top: 0;
-    transition: width 0ms,height 0ms,opacity .25s ease-out;
-    width: 0;
-}
-
-// On narrow screens, we use this overlay to close the left sidebar
-@media (max-width: $breakpoint-md) {
-    input:checked + label.overlay {
-        z-index: 1040;  // This puts it above the topbar, below the sidebar
-        height: 100%;
-        opacity: 1;
-        width: 100%;
-    }
-}