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
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
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
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".
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,
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 {
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.
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