[ptxdist] [PATCH 1/3] doc: fix CSS/JS files not getting picked up by sphinx 5.3.0

[ptxdist] [PATCH 1/3] doc: fix CSS/JS files not getting picked up by sphinx 5.3.0

[Roland Hieber]

Somewhen between v3.4.3 (Debian bullseye) and v5.3.0 (Debian bookworm),
sphinx stopped picking up our CSS and JS files from the html_context,
which has the effect that the styling of the HTML documentation looks
very broken when built with sphinx 5.3.0.

Instead of injecting the CSS and JS files into html_context, use the
dedicated variables html_css_files and html_js_files, which were
introduced in sphinx 1.8 (which came out in 2018). This mostly fixes the
layout with sphinx v5.3.0, apart from a small vertical space glitch in
the "View page source" link, which we will fix later.

Signed-off-by: Roland Hieber <rhi@pengutronix.de>
---
 doc/conf.py | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/doc/conf.py b/doc/conf.py
index 92594f4078a0..3e53aa4db20e 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -172,15 +172,16 @@ html_theme = 'sphinx_rtd_theme'
 
 html_static_path = ['_static']
 
-html_context = {
-    'css_files': ['_static/css/custom.css'],
-    'script_files': [
-        '_static/js/jquery-3.1.0.min.js',
-        '_static/underscore.js',
-        '_static/doctools.js',
-        '_static/js/main.js',
-    ],
-}
+html_css_files = [
+        'css/custom.css',
+]
+
+html_js_files = [
+        'js/jquery-3.1.0.min.js',
+        'underscore.js',
+        'doctools.js',
+        'js/main.js',
+]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-- 
2.39.2

[ptxdist] [PATCH 2/3] doc: custom.css: fix indentation

[Roland Hieber]

Make indentation consistent with the rest of the file.

Fixes: 876d0ff2cb0f2ef54f81 (2017-07-14, "doc: css: use more ptxdist-like colors for admonitions")
Signed-off-by: Roland Hieber <rhi@pengutronix.de>
---
 doc/_static/css/custom.css | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css
index 258e8f70ebfb..7efe0e101774 100644
--- a/doc/_static/css/custom.css
+++ b/doc/_static/css/custom.css
@@ -97,17 +97,17 @@ nav.wy-nav-side #menu-resize .fa:not(:first-child) {
 }
 
 .important {
-		background-color: #fff4dd !important;
+    background-color: #fff4dd !important;
 }
 .important .admonition-title {
-		background-color: #ff9b00 !important;
+    background-color: #ff9b00 !important;
 }
 
 .note {
-		background-color: #f2f9e5 !important;
+    background-color: #f2f9e5 !important;
 }
 .note .admonition-title {
-		background-color: #83983e !important;
+    background-color: #83983e !important;
 }
 
 .wy-table-responsive table.word-wrap td,
-- 
2.39.2

[ptxdist] [PATCH 3/3] doc: custom.css: fix "View Page Source" align with newer sphinx_rtd_theme

[Roland Hieber]

sphinx_rtd_theme PR #1073, which went into 1.2.0, removed the
vertical-align attribute for the "View Page Source" link, which does not
have a big impact on the vanilla sphinx_rtd_theme. However our custom
theme hacks add buttons left and right of the breadcrumbs which are
higher than the line height, and therefore our custom.css already
includes a "vertical-align: middle" to align the text of the chapter
marks with the surrounding buttons. However, this doesn't work for the
.wy-breadcrumbs-aside elements, which get floated right; therefore they
get rendered as "display: block" instead of "display: inline-block", and
according to the CSS specification, the "vertical-align" has no effect
on "display: block" elements. This has the effect that the "View Source"
link is now no longer aligned vertically, but instead is shifted upwards
relative to the baseline of the chapter marks.

The right way to have left-aligned chapter marks and right-aligned "View
Source" link would probably be a flex layout, but that would need
another layer of <div>s to group the left and right elements of the
navigation header, which we cannot do here as we only have control over
the CSS and not the page structure. Instead, re-apply the display and
padding that were removed in PR #1073 (and increase the padding to 7px
to account for or higher buttons), which does approximately the right
thing, and re-aligns the "View Source" link with the baseline of the
chapter marks again.

This has no effect on sphinx_rtd_theme < 1.2.0 since the a element and
the surrounding .wy-breadcrumbs-aside will be of the same height.

Link: https://github.com/readthedocs/sphinx_rtd_theme/pull/1073
Signed-off-by: Roland Hieber <rhi@pengutronix.de>
---
 doc/_static/css/custom.css | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css
index 7efe0e101774..27add44263d5 100644
--- a/doc/_static/css/custom.css
+++ b/doc/_static/css/custom.css
@@ -12,6 +12,11 @@
     vertical-align: middle;
 }
 
+/* "View Page Source" link */
+.wy-breadcrumbs .wy-breadcrumbs-aside > a {
+    display: inline-block;
+    padding: 7px;
+}
 
 /* links */
 .wy-menu-vertical a:active {
-- 
2.39.2

Re: [ptxdist] [APPLIED] doc: fix CSS/JS files not getting picked up by sphinx 5.3.0

[Michael Olbrich]

Thanks, applied as 244182364d60903ae07e2a2a583ea025d097426d.

Michael

[sent from post-receive hook]

On Thu, 11 May 2023 07:55:32 +0200, Roland Hieber <rhi@pengutronix.de> wrote:
> Somewhen between v3.4.3 (Debian bullseye) and v5.3.0 (Debian bookworm),
> sphinx stopped picking up our CSS and JS files from the html_context,
> which has the effect that the styling of the HTML documentation looks
> very broken when built with sphinx 5.3.0.
> 
> Instead of injecting the CSS and JS files into html_context, use the
> dedicated variables html_css_files and html_js_files, which were
> introduced in sphinx 1.8 (which came out in 2018). This mostly fixes the
> layout with sphinx v5.3.0, apart from a small vertical space glitch in
> the "View page source" link, which we will fix later.
> 
> Signed-off-by: Roland Hieber <rhi@pengutronix.de>
> Message-Id: <20230506202223.263380-1-rhi@pengutronix.de>
> Signed-off-by: Michael Olbrich <m.olbrich@pengutronix.de>
> 
> diff --git a/doc/conf.py b/doc/conf.py
> index 92594f4078a0..3e53aa4db20e 100644
> --- a/doc/conf.py
> +++ b/doc/conf.py
> @@ -172,15 +172,16 @@ html_theme = 'sphinx_rtd_theme'
>  
>  html_static_path = ['_static']
>  
> -html_context = {
> -    'css_files': ['_static/css/custom.css'],
> -    'script_files': [
> -        '_static/js/jquery-3.1.0.min.js',
> -        '_static/underscore.js',
> -        '_static/doctools.js',
> -        '_static/js/main.js',
> -    ],
> -}
> +html_css_files = [
> +        'css/custom.css',
> +]
> +
> +html_js_files = [
> +        'js/jquery-3.1.0.min.js',
> +        'underscore.js',
> +        'doctools.js',
> +        'js/main.js',
> +]
>  
>  # The name for this set of Sphinx documents.  If None, it defaults to
>  # "<project> v<release> documentation".

Re: [ptxdist] [APPLIED] doc: custom.css: fix indentation

[Michael Olbrich]

Thanks, applied as 257259c8021b87481ed94c8450d99e6bc937fb6c.

Michael

[sent from post-receive hook]

On Thu, 11 May 2023 07:55:33 +0200, Roland Hieber <rhi@pengutronix.de> wrote:
> Make indentation consistent with the rest of the file.
> 
> Fixes: 876d0ff2cb0f2ef54f81 (2017-07-14, "doc: css: use more ptxdist-like colors for admonitions")
> Signed-off-by: Roland Hieber <rhi@pengutronix.de>
> Message-Id: <20230506202223.263380-2-rhi@pengutronix.de>
> Signed-off-by: Michael Olbrich <m.olbrich@pengutronix.de>
> 
> diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css
> index 258e8f70ebfb..7efe0e101774 100644
> --- a/doc/_static/css/custom.css
> +++ b/doc/_static/css/custom.css
> @@ -97,17 +97,17 @@ nav.wy-nav-side #menu-resize .fa:not(:first-child) {
>  }
>  
>  .important {
> -		background-color: #fff4dd !important;
> +    background-color: #fff4dd !important;
>  }
>  .important .admonition-title {
> -		background-color: #ff9b00 !important;
> +    background-color: #ff9b00 !important;
>  }
>  
>  .note {
> -		background-color: #f2f9e5 !important;
> +    background-color: #f2f9e5 !important;
>  }
>  .note .admonition-title {
> -		background-color: #83983e !important;
> +    background-color: #83983e !important;
>  }
>  
>  .wy-table-responsive table.word-wrap td,

Re: [ptxdist] [APPLIED] doc: custom.css: fix "View Page Source" align with newer sphinx_rtd_theme

[Michael Olbrich]

Thanks, applied as ec2fe71855805d9d27c531be4bf69acdd34ba500.

Michael

[sent from post-receive hook]

On Thu, 11 May 2023 07:55:34 +0200, Roland Hieber <rhi@pengutronix.de> wrote:
> sphinx_rtd_theme PR #1073, which went into 1.2.0, removed the
> vertical-align attribute for the "View Page Source" link, which does not
> have a big impact on the vanilla sphinx_rtd_theme. However our custom
> theme hacks add buttons left and right of the breadcrumbs which are
> higher than the line height, and therefore our custom.css already
> includes a "vertical-align: middle" to align the text of the chapter
> marks with the surrounding buttons. However, this doesn't work for the
> .wy-breadcrumbs-aside elements, which get floated right; therefore they
> get rendered as "display: block" instead of "display: inline-block", and
> according to the CSS specification, the "vertical-align" has no effect
> on "display: block" elements. This has the effect that the "View Source"
> link is now no longer aligned vertically, but instead is shifted upwards
> relative to the baseline of the chapter marks.
> 
> The right way to have left-aligned chapter marks and right-aligned "View
> Source" link would probably be a flex layout, but that would need
> another layer of <div>s to group the left and right elements of the
> navigation header, which we cannot do here as we only have control over
> the CSS and not the page structure. Instead, re-apply the display and
> padding that were removed in PR #1073 (and increase the padding to 7px
> to account for or higher buttons), which does approximately the right
> thing, and re-aligns the "View Source" link with the baseline of the
> chapter marks again.
> 
> This has no effect on sphinx_rtd_theme < 1.2.0 since the a element and
> the surrounding .wy-breadcrumbs-aside will be of the same height.
> 
> Link: https://github.com/readthedocs/sphinx_rtd_theme/pull/1073
> Signed-off-by: Roland Hieber <rhi@pengutronix.de>
> Message-Id: <20230506202223.263380-3-rhi@pengutronix.de>
> Signed-off-by: Michael Olbrich <m.olbrich@pengutronix.de>
> 
> diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css
> index 7efe0e101774..27add44263d5 100644
> --- a/doc/_static/css/custom.css
> +++ b/doc/_static/css/custom.css
> @@ -12,6 +12,11 @@
>      vertical-align: middle;
>  }
>  
> +/* "View Page Source" link */
> +.wy-breadcrumbs .wy-breadcrumbs-aside > a {
> +    display: inline-block;
> +    padding: 7px;
> +}
>  
>  /* links */
>  .wy-menu-vertical a:active {

Re: [ptxdist] [PATCH 1/3] doc: fix CSS/JS files not getting picked up by sphinx 5.3.0

[Jonas Schmidt]

On Sat, May 06, 2023 at 10:22:21PM +0200, Roland Hieber wrote:
> Somewhen between v3.4.3 (Debian bullseye) and v5.3.0 (Debian bookworm),
> sphinx stopped picking up our CSS and JS files from the html_context,
> which has the effect that the styling of the HTML documentation looks
> very broken when built with sphinx 5.3.0.
> 
> Instead of injecting the CSS and JS files into html_context, use the
> dedicated variables html_css_files and html_js_files, which were
> introduced in sphinx 1.8 (which came out in 2018). This mostly fixes the
> layout with sphinx v5.3.0, apart from a small vertical space glitch in
> the "View page source" link, which we will fix later.
>
> Signed-off-by: Roland Hieber <rhi@pengutronix.de>
We had a simular issue and I was workting on an fix as well, but you were faster.

Tested-by: Jonas Schmidt  <j.schmidt@eckelmann.de>
Acked-by: Jonas Schmidt  <j.schmidt@eckelaman>
> ---
>  doc/conf.py | 19 ++++++++++---------
>  1 file changed, 10 insertions(+), 9 deletions(-)
> 
> diff --git a/doc/conf.py b/doc/conf.py
> index 92594f4078a0..3e53aa4db20e 100644
> --- a/doc/conf.py
> +++ b/doc/conf.py
> @@ -172,15 +172,16 @@ html_theme = 'sphinx_rtd_theme'
>  
>  html_static_path = ['_static']
>  
> -html_context = {
> -    'css_files': ['_static/css/custom.css'],
> -    'script_files': [
> -        '_static/js/jquery-3.1.0.min.js',
> -        '_static/underscore.js',
> -        '_static/doctools.js',
> -        '_static/js/main.js',
> -    ],
> -}
> +html_css_files = [
> +        'css/custom.css',
> +]
> +
> +html_js_files = [
> +        'js/jquery-3.1.0.min.js',
> +        'underscore.js',
> +        'doctools.js',
> +        'js/main.js',
> +]
>  
>  # The name for this set of Sphinx documents.  If None, it defaults to
>  # "<project> v<release> documentation".
> -- 
> 2.39.2

Best regards
Jonas Schmidt.

Re: [ptxdist] [PATCH 1/3] doc: fix CSS/JS files not getting picked up by sphinx 5.3.0

[Gavin Schenk]

Hi,

> On Sat, May 06, 2023 at 10:22:21PM +0200, Roland Hieber wrote:
>> Somewhen between v3.4.3 (Debian bullseye) and v5.3.0 (Debian bookworm),
>> sphinx stopped picking up our CSS and JS files from the html_context,
>> which has the effect that the styling of the HTML documentation looks
>> very broken when built with sphinx 5.3.0.
>> 
>> Instead of injecting the CSS and JS files into html_context, use the
>> dedicated variables html_css_files and html_js_files, which were
>> introduced in sphinx 1.8 (which came out in 2018). This mostly fixes the
>> layout with sphinx v5.3.0, apart from a small vertical space glitch in
>> the "View page source" link, which we will fix later.
>>
>> Signed-off-by: Roland Hieber <rhi@pengutronix.de>
> We had a simular issue and I was workting on an fix as well, but you were faster.
>
> Tested-by: Jonas Schmidt  <j.schmidt@eckelmann.de>
> Acked-by: Jonas Schmidt  <j.schmidt@eckelaman>

^- Typo here, shall be: Jonas Schmidt <j.schmidt@eckelmann.de>

Maybe a magic keystroke in neovim ?! :)

LG
Gavin Schenk