From 9f56b6a5255179b2d160e6c0e11be1019ed16fbd Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Sun, 29 Jan 2023 17:32:48 +0000 Subject: [PATCH 1/9] Implement support for sticky banners --- .../pep_theme/static/sticky_banner.js | 17 +++++++++++++++++ .../pep_theme/static/style.css | 6 ++++++ .../pep_theme/templates/page.html | 1 + 3 files changed, 24 insertions(+) create mode 100644 pep_sphinx_extensions/pep_theme/static/sticky_banner.js diff --git a/pep_sphinx_extensions/pep_theme/static/sticky_banner.js b/pep_sphinx_extensions/pep_theme/static/sticky_banner.js new file mode 100644 index 00000000000..de175f30c32 --- /dev/null +++ b/pep_sphinx_extensions/pep_theme/static/sticky_banner.js @@ -0,0 +1,17 @@ +"use strict"; + +// Inject a style element into the document head that adds scroll-margin-top to +// all elements with an id attribute. This is used to offset the scroll position +// when clicking on a link to an element with an id attribute. The offset is +// equal to the height of the sticky banner. +document.addEventListener("DOMContentLoaded", () => { + let stickyBanners = document.getElementsByClassName("sticky-banner"); + if (!stickyBanners) { + return; + } + let stickyBanner = stickyBanners[0]; + let node = document.createElement("style"); + let text = document.createTextNode(":target { scroll-margin-top: " + stickyBanner.offsetHeight + "px; }") + node.appendChild(text); + document.head.appendChild(node); +}); diff --git a/pep_sphinx_extensions/pep_theme/static/style.css b/pep_sphinx_extensions/pep_theme/static/style.css index 999e638e037..f49950a14dc 100644 --- a/pep_sphinx_extensions/pep_theme/static/style.css +++ b/pep_sphinx_extensions/pep_theme/static/style.css @@ -405,3 +405,9 @@ dl.footnote > dd { white-space: nowrap !important; border: 0 !important; } + +/* Sticky banners */ +.sticky-banner { + top: 0; + position: sticky; +} diff --git a/pep_sphinx_extensions/pep_theme/templates/page.html b/pep_sphinx_extensions/pep_theme/templates/page.html index 6902e559264..7daf060cfd5 100644 --- a/pep_sphinx_extensions/pep_theme/templates/page.html +++ b/pep_sphinx_extensions/pep_theme/templates/page.html @@ -51,5 +51,6 @@

Contents

+ From a28753316d41385e4215c8a91834f40cf076ab6c Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Sun, 29 Jan 2023 17:33:00 +0000 Subject: [PATCH 2/9] Remove repeated specification of base banner class --- .../pep_processor/parsing/pep_banner_directive.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py b/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py index 11345e11871..3c84bfc708c 100644 --- a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py +++ b/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py @@ -23,7 +23,7 @@ class PEPBanner(rst.Directive): admonition_post_text = "" admonition_class = nodes.important - css_classes = ["pep-banner"] + css_classes = [] def run(self) -> list[nodes.admonition]: @@ -48,7 +48,7 @@ def run(self) -> list[nodes.admonition]: source_lines = [pre_text] + list(self.content or []) + [post_text] admonition_node = self.admonition_class( - "\n".join(source_lines), classes=self.css_classes) + "\n".join(source_lines), classes=["pep-banner"] + self.css_classes) admonition_node.append(pre_text_node) if self.content: @@ -75,7 +75,7 @@ class CanonicalDocBanner(PEPBanner): "See :pep:`1` for how to propose changes." ) - css_classes = [*PEPBanner.css_classes, "canonical-doc"] + css_classes = ["canonical-doc"] @@ -98,4 +98,4 @@ class CanonicalPyPASpecBanner(PEPBanner): "for how to propose changes." ) - css_classes = [*PEPBanner.css_classes, "canonical-pypa-spec"] + css_classes = ["canonical-pypa-spec"] From 9a3574029a918d4d6e31a5d1a88437a3681d2ec3 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Sun, 29 Jan 2023 17:33:06 +0000 Subject: [PATCH 3/9] Replace bespoke and unused banner classes with `sticky-banner` These banners are now sticky, ensuring that they are visible throughout the document. --- .../pep_processor/parsing/pep_banner_directive.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py b/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py index 3c84bfc708c..6f488e07469 100644 --- a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py +++ b/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py @@ -75,7 +75,7 @@ class CanonicalDocBanner(PEPBanner): "See :pep:`1` for how to propose changes." ) - css_classes = ["canonical-doc"] + css_classes = ["sticky-banner"] @@ -98,4 +98,4 @@ class CanonicalPyPASpecBanner(PEPBanner): "for how to propose changes." ) - css_classes = ["canonical-pypa-spec"] + css_classes = ["sticky-banner"] From 7bdba971e8ce2a3e72b2fc9688b82a608158a7b3 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Sun, 29 Jan 2023 17:33:12 +0000 Subject: [PATCH 4/9] Use attention admonition for PyPA PEP banners --- .../pep_processor/parsing/pep_banner_directive.py | 1 + 1 file changed, 1 insertion(+) diff --git a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py b/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py index 6f488e07469..dd6a642443e 100644 --- a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py +++ b/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py @@ -97,5 +97,6 @@ class CanonicalPyPASpecBanner(PEPBanner): "`__ " "for how to propose changes." ) + admonition_class = nodes.attention css_classes = ["sticky-banner"] From 418eec59b96a66eb038886e87740633962697845 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Sun, 29 Jan 2023 17:33:16 +0000 Subject: [PATCH 5/9] Make attention admonition more attention grabbing --- pep_sphinx_extensions/pep_theme/static/style.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pep_sphinx_extensions/pep_theme/static/style.css b/pep_sphinx_extensions/pep_theme/static/style.css index f49950a14dc..6ee8f8e654c 100644 --- a/pep_sphinx_extensions/pep_theme/static/style.css +++ b/pep_sphinx_extensions/pep_theme/static/style.css @@ -321,10 +321,10 @@ div.error { div.warning { background-color: var(--colour-warning); } +div.attention, div.caution { background-color: var(--colour-caution); } -div.attention, div.important { background-color: var(--colour-attention); } From 6041230ea9cad42b26f6b9fa16b82625dd23d13f Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Sat, 11 Mar 2023 11:55:49 +0000 Subject: [PATCH 6/9] fixup! Implement support for sticky banners --- .../pep_theme/static/sticky_banner.js | 29 +++++++++++++------ 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/pep_sphinx_extensions/pep_theme/static/sticky_banner.js b/pep_sphinx_extensions/pep_theme/static/sticky_banner.js index de175f30c32..7ea90e60854 100644 --- a/pep_sphinx_extensions/pep_theme/static/sticky_banner.js +++ b/pep_sphinx_extensions/pep_theme/static/sticky_banner.js @@ -5,13 +5,24 @@ // when clicking on a link to an element with an id attribute. The offset is // equal to the height of the sticky banner. document.addEventListener("DOMContentLoaded", () => { - let stickyBanners = document.getElementsByClassName("sticky-banner"); - if (!stickyBanners) { - return; - } - let stickyBanner = stickyBanners[0]; - let node = document.createElement("style"); - let text = document.createTextNode(":target { scroll-margin-top: " + stickyBanner.offsetHeight + "px; }") - node.appendChild(text); - document.head.appendChild(node); + const stickyBanners = document.getElementsByClassName("sticky-banner"); + if (!stickyBanners) { + return; + } + + const stickyBanner = stickyBanners[0]; + const node = document.createElement("style"); + node.id = "sticky-banner-style"; + document.head.appendChild(node); + + function adjustBannerMargin() { + const text = document.createTextNode( + ":target { scroll-margin-top: " + stickyBanner.offsetHeight + "px; }" + ); + node.replaceChildren(text); + } + + adjustBannerMargin(); + document.addEventListener("resize", adjustBannerMargin); + document.addEventListener("load", adjustBannerMargin); }); From 3ee8d18fce48fa32e573876cb74945ef632f9452 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Sat, 11 Mar 2023 11:56:39 +0000 Subject: [PATCH 7/9] fixup! Implement support for sticky banners --- pep_sphinx_extensions/pep_theme/static/sticky_banner.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pep_sphinx_extensions/pep_theme/static/sticky_banner.js b/pep_sphinx_extensions/pep_theme/static/sticky_banner.js index 7ea90e60854..cc2ceb3dd0c 100644 --- a/pep_sphinx_extensions/pep_theme/static/sticky_banner.js +++ b/pep_sphinx_extensions/pep_theme/static/sticky_banner.js @@ -6,7 +6,7 @@ // equal to the height of the sticky banner. document.addEventListener("DOMContentLoaded", () => { const stickyBanners = document.getElementsByClassName("sticky-banner"); - if (!stickyBanners) { + if (!stickyBanners.length) { return; } From 4546e7a0d511138dd6194db6aa4e2f9da69b2962 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Sat, 11 Mar 2023 11:58:35 +0000 Subject: [PATCH 8/9] Revert "Replace bespoke and unused banner classes with `sticky-banner`" This reverts commit 9a3574029a918d4d6e31a5d1a88437a3681d2ec3. --- .../pep_processor/parsing/pep_banner_directive.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py b/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py index dd6a642443e..a5be6a0bd4e 100644 --- a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py +++ b/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py @@ -75,7 +75,7 @@ class CanonicalDocBanner(PEPBanner): "See :pep:`1` for how to propose changes." ) - css_classes = ["sticky-banner"] + css_classes = ["canonical-doc"] @@ -99,4 +99,4 @@ class CanonicalPyPASpecBanner(PEPBanner): ) admonition_class = nodes.attention - css_classes = ["sticky-banner"] + css_classes = ["canonical-pypa-spec"] From f2e051973bf5d372f8a5b9ede69c529a8562fc3f Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Sat, 11 Mar 2023 11:59:16 +0000 Subject: [PATCH 9/9] Add back the sticky-banner CSS class --- .../pep_processor/parsing/pep_banner_directive.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py b/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py index a5be6a0bd4e..f3a55270cd7 100644 --- a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py +++ b/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py @@ -75,7 +75,7 @@ class CanonicalDocBanner(PEPBanner): "See :pep:`1` for how to propose changes." ) - css_classes = ["canonical-doc"] + css_classes = ["canonical-doc", "sticky-banner"] @@ -99,4 +99,4 @@ class CanonicalPyPASpecBanner(PEPBanner): ) admonition_class = nodes.attention - css_classes = ["canonical-pypa-spec"] + css_classes = ["canonical-pypa-spec", "sticky-banner"]