NEW: Adding a section for footer-content like in sphinx-basic-ng (#861)

pydata · Aug 18, 2022 · 4b97fe0 · 4b97fe0
1 parent 51219fe
commit 4b97fe0
Show file tree

Hide file tree

Showing 10 changed files with 139 additions and 78 deletions.
diff --git a/docs/user_guide/layout.rst b/docs/user_guide/layout.rst
@@ -79,38 +79,63 @@ You can click on section titles to learn more about them and some basic layout c
         Links between pages in the active section.
 
     .. grid-item::
-        :padding: 2
-        :outline:
-        :columns: 6
-        :class: content
+        :columns: 8
 
-        .. button-ref:: layout-article-header
-            :color: primary
-            :outline:
+        .. grid::
+            :margin: 0
+            :gutter: 0
 
-            Article Header
+            .. grid-item::
+                :class: content
+                :padding: 2
+                :columns: 8
+                :outline:
 
-        **Article Content**
+                .. button-ref:: layout-article-header
+                    :color: primary
+                    :outline:
 
-        .. button-ref:: layout-article-footer
-            :color: primary
-            :outline:
+                    Article Header
 
-            Article Footer
+                **Article Content**
 
-    .. grid-item::
-        :padding: 2
-        :outline:
-        :columns: 2
-        :class: sidebar-secondary
+                .. button-ref:: layout-article-footer
+                    :color: primary
+                    :outline:
 
-        .. button-ref:: layout-sidebar-secondary
-            :color: primary
+                    Article Footer
+
+            .. grid-item::
+                :padding: 2
+                :columns: 4
+                :outline:
+                :class: sidebar-secondary
+
+                .. button-ref:: layout-sidebar-secondary
+                    :color: primary
+                    :outline:
+
+                    Secondary Sidebar
+
+                Within-page header links
+
+        .. grid::
+            :margin: 0
+            :gutter: 0
             :outline:
 
-            Secondary Sidebar
+            .. grid-item::
+                :padding: 2
+                :columns: 12
+                :class: footer-content
+
+                .. button-ref:: layout-footer-content
+                    :color: primary
+                    :outline:
+
+                    Footer content
+
 
-        Within-page header links
 
     .. grid-item::
         :padding: 2
@@ -322,12 +347,21 @@ use this pattern:
      "**": []
    }
 
+.. _layout-footer-content:
+
+Footer Content
+==============
+
+The footer content is a narrow bar spanning the article’s content and secondary sidebar.
+It does not contain anything immediately viewable to the reader, but is kept as a placeholder in case theme developers wish to re-use it in the future.
+
+
 .. _layout-sidebar-secondary:
 
 Secondary Sidebar (right)
 =========================
 
-The in-page sidebar is just to the right of a page's main content, and is
+The in-page sidebar is just to the right of a page's article content, and is
 configured in ``conf.py`` with ``html_theme_options['page_sidebar_items']``.
 
 By default, it has the following templates:
@@ -364,7 +398,7 @@ at the bottom. You can hide these buttons with the following configuration:
 Footer
 ======
 
-The footer is just below a page's main content, and is configured in ``conf.py``
+The footer is just below a page’s main content, and is configured in ``conf.py``
 with ``html_theme_options['footer_items']``.
 
 By default, it has the following templates:

diff --git a/src/pydata_sphinx_theme/assets/styles/sections/_article.scss b/src/pydata_sphinx_theme/assets/styles/sections/_article.scss
@@ -1,22 +1,33 @@
 /**
  * Main content area
  */
-.bd-content {
-  display: flex;
+.bd-main {
+  flex-grow: 1;
   flex-direction: column;
+  display: flex;
+  min-width: 0;
 
-  // Max-width is slightly more than the W3 since our docs often have images.
-  // We shoot for about 100 characters per line instead of 80.
-  // ref: https://www.w3.org/WAI/tutorials/page-structure/styling/#line-length
-  max-width: 60em;
-  overflow-x: auto; // Prevent wide content from pushing off the secondary sidebar
-  padding: 1rem;
-
-  .bd-article {
-    // Give a bit more verticle spacing on wide screens
-    @include media-breakpoint-up($breakpoint-sidebar-secondary) {
-      padding-top: 2rem;
-      padding-left: 2rem;
+  .bd-content {
+    display: flex;
+    justify-content: center;
+    height: 100%;
+    .bd-article-container {
+      justify-content: space-between;
+      display: flex;
+      flex-direction: column;
+      // Max-width is slightly more than the W3 since our docs often have images.
+      // We shoot for about 100 characters per line instead of 80.
+      // ref: https://www.w3.org/WAI/tutorials/page-structure/styling/#line-length
+      max-width: 60em;
+      overflow-x: auto; // Prevent wide content from pushing off the secondary sidebar
+      padding: 1rem;
+      .bd-article {
+        // Give a bit more verticle spacing on wide screens
+        @include media-breakpoint-up($breakpoint-sidebar-secondary) {
+          padding-top: 2rem;
+          padding-left: 2rem;
+        }
+      }
     }
   }
 }
diff --git a/src/pydata_sphinx_theme/assets/styles/sections/_container.scss b/src/pydata_sphinx_theme/assets/styles/sections/_container.scss
@@ -1,10 +1,16 @@
 .bd-container {
   flex-grow: 1;
   display: flex;
-  flex-direction: column;
+  justify-content: center;
 
   .bd-container__inner {
-    flex-grow: 1;
-    justify-content: center;
+    display: flex;
+  }
+}
+
+.bd-page-width {
+  width: 100%;
+  @include media-breakpoint-up(lg) {
+    max-width: $breakpoint-page-width;
   }
 }
diff --git a/src/pydata_sphinx_theme/assets/styles/sections/_header.scss b/src/pydata_sphinx_theme/assets/styles/sections/_header.scss
@@ -17,8 +17,10 @@
   width: 100%;
   padding: 0.5rem 0;
   max-width: 100vw;
-
+  justify-content: center;
   .bd-header__inner {
+    display: flex;
+    align-items: center;
     height: 100%;
     padding-left: 1rem;
     padding-right: 1rem;

diff --git a/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-primary.scss b/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-primary.scss
@@ -7,7 +7,6 @@
   display: flex;
   flex-direction: column;
   gap: 1rem;
-
   max-height: calc(100vh - var(--pst-header-height));
   position: sticky;
   top: var(--pst-header-height);

diff --git a/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-secondary.scss b/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-secondary.scss
@@ -5,6 +5,7 @@
 .bd-sidebar-secondary {
   display: flex;
   order: 2;
+  flex-shrink: 0;
   flex-direction: column;
   position: sticky;
   top: var(--pst-header-height);
@@ -16,7 +17,7 @@
   }
 
   padding: 2rem 1rem 1rem 1rem;
-  @include make-col(2);
+  width: var(--pst-sidebar-secondary);
 
   // Color and border
   background-color: var(--pst-color-background);

diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_layout.scss b/src/pydata_sphinx_theme/assets/styles/variables/_layout.scss
@@ -7,6 +7,7 @@
   // Article header is 66% of Header
   --pst-header-height: 3rem;
   --pst-header-article-height: calc(var(--pst-header-height) * 2 / 3);
+  --pst-sidebar-secondary: 17rem;
 }
 
 /*******************************************************************************
@@ -19,6 +20,7 @@
 */
 $breakpoint-sidebar-primary: lg; // When we collapse the primary sidebar
 $breakpoint-sidebar-secondary: xl; // When we collapse the secondary sidebar
+$breakpoint-page-width: 88rem; // taken from sphinx-basic-ng, which we are ultimately going to inherit
 
 /*******************************************************************************
 * Define the animation behaviour

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html
@@ -78,45 +78,50 @@
   </nav>
   {% endblock %}
 
-  <div class="bd-container container-xl">
-    <div class="bd-container__inner row">
+  <div class="bd-container">
+    <div class="bd-container__inner bd-page-width">
       {# Primary sidebar #}
       <div class="bd-sidebar-primary bd-sidebar{% if not sidebars %} hide-on-wide{% endif %}">
         {% include "sections/sidebar-primary.html" %}
       </div>
-
-      {# Secondary sidebar #}
-      {% block docs_toc %}
-      {% if not remove_sidebar_secondary %}
-        <div class="bd-sidebar-secondary bd-toc">
-          {% include "sections/sidebar-secondary.html" %}
-        </div>
-      {% endif %}
-      {% endblock %}
-
-      {# Main content area #}
-      {% block docs_main %}
-      <div class="bd-content col">
-          {# Article header #}
-          <div class="bd-header-article">
-              {% include "sections/header-article.html" %}
+      <main class="bd-main">
+        {# Main content area #}
+        {% block docs_main %}
+        <div class="bd-content">
+          <div class="bd-article-container">
+            {# Article header #}
+            <div class="bd-header-article">
+                {% include "sections/header-article.html" %}
+            </div>
+            {# Article content #}
+            {% block docs_body %}
+            <article class="bd-article" role="main">
+              {% block body %} {% endblock %}
+            </article>
+            {% endblock %}
+            {# Article Footer #}
+            {% if theme_show_prev_next %}
+            <footer class="bd-footer-article">
+                {% include "sections/footer-article.html" %}
+            </footer>
+            {% endif %}
           </div>
-
-          {# Article content #}
-          {% block docs_body %}
-          <article class="bd-article" role="main">
-            {% block body %} {% endblock %}
-          </article>
-          {% endblock %}
-
-          {# Article Footer #}
-          {% if theme_show_prev_next %}
-          <footer class="bd-footer-article">
-              {% include "sections/footer-article.html" %}
-          </footer>
+          {# Secondary sidebar #}
+          {% block docs_toc %}
+          {% if not remove_sidebar_secondary %}
+            <div class="bd-sidebar-secondary bd-toc">
+              {% include "sections/sidebar-secondary.html" %}
+            </div>
           {% endif %}
-      </div>
-      {% endblock %}
+          {% endblock %}
+        </div>
+        <footer class="bd-footer-content">
+          <div class="bd-footer-content__inner">
+            {% include "sections/footer-content.html" %}
+          </div>
+        </footer>
+        {% endblock %}
+      </main>
     </div>
   </div>
 

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/footer-content.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/footer-content.html
@@ -0,0 +1 @@
+{#- Intentionally empty in case others want to add something -#}
diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/header.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/header.html
@@ -1,4 +1,4 @@
-<div class="bd-header__inner container-xl">
+<div class="bd-header__inner bd-page-width">
   <label class="sidebar-toggle primary-toggle" for="__primary">
       <span class="fas fa-bars"></span>
   </label>