From 4b97fe03821b0a13a97417147b1eb19cba67f2d2 Mon Sep 17 00:00:00 2001 From: AakashGC Date: Thu, 18 Aug 2022 17:35:56 +1000 Subject: [PATCH] NEW: Adding a section for footer-content like in sphinx-basic-ng (#861) --- docs/user_guide/layout.rst | 82 +++++++++++++------ .../assets/styles/sections/_article.scss | 39 +++++---- .../assets/styles/sections/_container.scss | 12 ++- .../assets/styles/sections/_header.scss | 4 +- .../styles/sections/_sidebar-primary.scss | 1 - .../styles/sections/_sidebar-secondary.scss | 3 +- .../assets/styles/variables/_layout.scss | 2 + .../theme/pydata_sphinx_theme/layout.html | 71 ++++++++-------- .../sections/footer-content.html | 1 + .../pydata_sphinx_theme/sections/header.html | 2 +- 10 files changed, 139 insertions(+), 78 deletions(-) create mode 100644 src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/footer-content.html diff --git a/docs/user_guide/layout.rst b/docs/user_guide/layout.rst index c0aafef42..e4deded42 100644 --- 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 index 2456e2521..e9f3856ee 100644 --- 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 index 418651f14..442f442d1 100644 --- 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 index 3cd8fe995..78dc30ece 100644 --- 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 index 68204d2c6..714c8bde4 100644 --- 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 index 58391e350..986eadfa6 100644 --- 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 index c6d3b05a4..d2d45a6f8 100644 --- 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 index 270d0cb9a..d99fa5e39 100644 --- 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 @@ {% endblock %} -
-
+
+
{# Primary sidebar #}
{% include "sections/sidebar-primary.html" %}
- - {# Secondary sidebar #} - {% block docs_toc %} - {% if not remove_sidebar_secondary %} -
- {% include "sections/sidebar-secondary.html" %} -
- {% endif %} - {% endblock %} - - {# Main content area #} - {% block docs_main %} -
- {# Article header #} -
- {% include "sections/header-article.html" %} +
+ {# Main content area #} + {% block docs_main %} +
+
+ {# Article header #} +
+ {% include "sections/header-article.html" %} +
+ {# Article content #} + {% block docs_body %} +
+ {% block body %} {% endblock %} +
+ {% endblock %} + {# Article Footer #} + {% if theme_show_prev_next %} +
+ {% include "sections/footer-article.html" %} +
+ {% endif %}
- - {# Article content #} - {% block docs_body %} -
- {% block body %} {% endblock %} -
- {% endblock %} - - {# Article Footer #} - {% if theme_show_prev_next %} -
- {% include "sections/footer-article.html" %} -
+ {# Secondary sidebar #} + {% block docs_toc %} + {% if not remove_sidebar_secondary %} +
+ {% include "sections/sidebar-secondary.html" %} +
{% endif %} -
- {% endblock %} + {% endblock %} +
+
+
+ {% include "sections/footer-content.html" %} +
+
+ {% endblock %} +
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 new file mode 100644 index 000000000..00bdf56c4 --- /dev/null +++ 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 index f52533bbd..2008d4ef5 100644 --- 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 @@ -
+