For a long time we have rejoiced that our HTML output from Sphinx is far
better than what we got from the old DocBook toolchain. But it still
leaves a lot to be desired; the following is an attempt to improve the
situation somewhat.
Sphinx has a theming mechanism for HTML rendering. Since the kernel's
adoption of Sphinx, we have been using the "Read The Docs" theme — a choice
made in a bit of a hurry to have *something* while figuring out the rest.
RTD is OK, but it is not hugely attractive, requires the installation of an
extra package, and does not observe all of the Sphinx configuration
parameters. Among other things, that makes it hard to put reasonable
contents into the left column in the HTML output.
The Alabaster theme is the default for Sphinx installations, and is bundled
with Sphinx itself. It has (IMO) nicer output and gives us the control
that we need.
So: switch to Alabaster. Additional patches adjust the documentation and
remove the RTD references from scripts/sphinx-pre-install.
The final patch changes the way that kerneldoc declarations are rendered to
(IMO) improve readability. That requires some changes to kernel-doc to
output a new container block and some CSS tweaks to improve things overall.
It should be noted that I have a long history of inflicting ugly web
designs on the net; this work is a start, but I think we could do far
better yet. It would be great if somebody who actually enjoys working with
CSS and such would help to improve what we have.
As before, I've put a copy of the rendered docs at:
https://static.lwn.net/kerneldoc/
To compare the kerneldoc changes specifically, pick a page that includes a
lot of definitions; for example:
https://static.lwn.net/kerneldoc/driver-api/media/drivers/frontends.html
vs.
https://www.kernel.org/doc/html/latest/driver-api/media/drivers/frontends.html
Jonathan Corbet (5):
docs: Switch the default HTML theme to alabaster
docs: tweak some Alabaster style parameters
docs: update sphinx.rst to reflect the default theme change
docs: sphinx-pre-install: don't require the RTD theme
docs: improve the HTML formatting of kerneldoc comments
Documentation/conf.py | 27 ++++++++++++-
Documentation/doc-guide/sphinx.rst | 16 +++-----
Documentation/sphinx-static/custom.css | 25 +++++++++++++
Documentation/sphinx/requirements.txt | 1 -
scripts/kernel-doc | 52 ++++++++++++++++----------
scripts/sphinx-pre-install | 8 ----
6 files changed, 87 insertions(+), 42 deletions(-)
create mode 100644 Documentation/sphinx-static/custom.css
--
2.37.2
We don't default to the RTD theme anymore, so sphinx-pre-install need not
insist on installing it.
Signed-off-by: Jonathan Corbet <[email protected]>
---
Documentation/sphinx/requirements.txt | 1 -
scripts/sphinx-pre-install | 8 --------
2 files changed, 9 deletions(-)
diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
index 2c573541ab71..335b53df35e2 100644
--- a/Documentation/sphinx/requirements.txt
+++ b/Documentation/sphinx/requirements.txt
@@ -1,4 +1,3 @@
# jinja2>=3.1 is not compatible with Sphinx<4.0
jinja2<3.1
-sphinx_rtd_theme
Sphinx==2.4.4
diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index ec84fc62774e..1fb88fdceec3 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -362,7 +362,6 @@ sub give_debian_hints()
{
my %map = (
"python-sphinx" => "python3-sphinx",
- "sphinx_rtd_theme" => "python3-sphinx-rtd-theme",
"ensurepip" => "python3-venv",
"virtualenv" => "virtualenv",
"dot" => "graphviz",
@@ -397,7 +396,6 @@ sub give_redhat_hints()
{
my %map = (
"python-sphinx" => "python3-sphinx",
- "sphinx_rtd_theme" => "python3-sphinx_rtd_theme",
"virtualenv" => "python3-virtualenv",
"dot" => "graphviz",
"convert" => "ImageMagick",
@@ -475,7 +473,6 @@ sub give_opensuse_hints()
{
my %map = (
"python-sphinx" => "python3-sphinx",
- "sphinx_rtd_theme" => "python3-sphinx_rtd_theme",
"virtualenv" => "python3-virtualenv",
"dot" => "graphviz",
"convert" => "ImageMagick",
@@ -523,7 +520,6 @@ sub give_mageia_hints()
{
my %map = (
"python-sphinx" => "python3-sphinx",
- "sphinx_rtd_theme" => "python3-sphinx_rtd_theme",
"virtualenv" => "python3-virtualenv",
"dot" => "graphviz",
"convert" => "ImageMagick",
@@ -567,7 +563,6 @@ sub give_mageia_hints()
sub give_arch_linux_hints()
{
my %map = (
- "sphinx_rtd_theme" => "python-sphinx_rtd_theme",
"virtualenv" => "python-virtualenv",
"dot" => "graphviz",
"convert" => "imagemagick",
@@ -598,7 +593,6 @@ sub give_arch_linux_hints()
sub give_gentoo_hints()
{
my %map = (
- "sphinx_rtd_theme" => "dev-python/sphinx_rtd_theme",
"virtualenv" => "dev-python/virtualenv",
"dot" => "media-gfx/graphviz",
"convert" => "media-gfx/imagemagick",
@@ -895,7 +889,6 @@ sub recommend_sphinx_version($)
$verbose_warn_install = 0;
add_package("python-sphinx", 0);
- check_python_module("sphinx_rtd_theme", 1);
check_distros();
@@ -968,7 +961,6 @@ sub check_needs()
check_perl_module("Pod::Usage", 0);
check_program("make", 0);
check_program("gcc", 0);
- check_python_module("sphinx_rtd_theme", 1) if (!$virtualenv);
check_program("dot", 1);
check_program("convert", 1);
--
2.37.2
The read-the-docs theme is not entirely attractive and doesn't give us
control over the left column. "Alabaster" is deemed the default Sphinx
theme, it is currently maintained and shipped bundled with Sphinx itself,
so there is no need to install it separately. Switch over to this theme as
the default for building kernel documentation; the DOCS_THEME environment
variable can still be used to select a different theme.
Signed-off-by: Jonathan Corbet <[email protected]>
---
Documentation/conf.py | 26 ++++++++++++++++++++++++--
1 file changed, 24 insertions(+), 2 deletions(-)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 22c9d4df1967..629f4afeb0eb 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -194,6 +194,24 @@ finally:
else:
version = release = "unknown version"
+#
+# HACK: there seems to be no easy way for us to get at the version and
+# release information passed in from the makefile...so go pawing through the
+# command-line options and find it for ourselves.
+#
+def get_cline_version():
+ c_version = c_release = ''
+ for arg in sys.argv:
+ if arg.startswith('version='):
+ c_version = arg[8:]
+ elif arg.startswith('release='):
+ c_release = arg[8:]
+ if c_version:
+ if c_release:
+ return c_version + '-' + c_release
+ return c_version
+ return version # Whatever we came up with before
+
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
@@ -247,7 +265,7 @@ highlight_language = 'none'
# a list of builtin themes.
# Default theme
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'alabaster'
html_css_files = []
if "DOCS_THEME" in os.environ:
@@ -324,6 +342,10 @@ if html_theme == 'classic':
'bodyfont': "serif",
'headfont': "sans-serif",
}
+else:
+ html_theme_options = {
+ 'description': get_cline_version(),
+ }
sys.stderr.write("Using %s theme\n" % html_theme)
@@ -371,7 +393,7 @@ html_use_smartypants = False
# Custom sidebar templates, maps document names to template names.
# Note that the RTD theme ignores this
-html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']}
+html_sidebars = { '**': ["about.html", 'searchbox.html', 'localtoc.html', 'sourcelink.html']}
# Additional templates that should be rendered to pages, maps page names to
# template names.
--
2.37.2
Hi Jon,
Em Tue, 4 Oct 2022 14:12:17 -0600
Jonathan Corbet <[email protected]> escreveu:
> For a long time we have rejoiced that our HTML output from Sphinx is far
> better than what we got from the old DocBook toolchain. But it still
> leaves a lot to be desired; the following is an attempt to improve the
> situation somewhat.
>
> Sphinx has a theming mechanism for HTML rendering. Since the kernel's
> adoption of Sphinx, we have been using the "Read The Docs" theme — a choice
> made in a bit of a hurry to have *something* while figuring out the rest.
> RTD is OK, but it is not hugely attractive, requires the installation of an
> extra package, and does not observe all of the Sphinx configuration
> parameters. Among other things, that makes it hard to put reasonable
> contents into the left column in the HTML output.
>
> The Alabaster theme is the default for Sphinx installations, and is bundled
> with Sphinx itself. It has (IMO) nicer output and gives us the control
> that we need.
Nice to see it defaulting to one of the bundled themes! Not needing to
install a theme by default is a nice addition.
> So: switch to Alabaster. Additional patches adjust the documentation and
> remove the RTD references from scripts/sphinx-pre-install.
>
> The final patch changes the way that kerneldoc declarations are rendered to
> (IMO) improve readability. That requires some changes to kernel-doc to
> output a new container block and some CSS tweaks to improve things overall.
>
> It should be noted that I have a long history of inflicting ugly web
> designs on the net; this work is a start, but I think we could do far
> better yet. It would be great if somebody who actually enjoys working with
> CSS and such would help to improve what we have.
>
> As before, I've put a copy of the rendered docs at:
>
> https://static.lwn.net/kerneldoc/
>
> To compare the kerneldoc changes specifically, pick a page that includes a
> lot of definitions; for example:
>
> https://static.lwn.net/kerneldoc/driver-api/media/drivers/frontends.html
> vs.
> https://www.kernel.org/doc/html/latest/driver-api/media/drivers/frontends.html
There's one change there that I didn't like much: at the original page,
the index shows the full index, allowing to see exactly on what part of the
index the page is sitting, e. g:
...
The Linux driver implementer's API guide
Media subsystem kernel internal API
1. Media Subsystem Profile
2. Video4Linux devices
3. Digital TV (DVB) devices
4. Remote Controller devices
5. Media Controller devices
6. CEC Kernel Support
7. Pixel data transmitter and receiver drivers
8. Writing camera sensor drivers
9. Media driver-specific documentation
9.1. Video4Linux (V4L) drivers
9.2. Digital TV drivers
While, after the change, it shows only:
Table of Contents
9.2.2. Frontend drivers
9.2.2.1. Frontend attach headers
IMO, the RTD's index output is a lot more useful, as someone reading this
would very likely need/want to navigate to other chapters of the same
part of the documentation, allowing to quickly navigate outside the
item 9.2.2.
On the other hand, hiding the books outside the kAPI guide makes sense.
I would play with the sidebar options used by Alabaster in order to
try to make the TOC more useful.
-
On a side note, one thing I miss on all default themes is a way to dynamically
use dark mode. That's btw why I ended adding non-default support for
'sphinx_rtd_dark_mode' (which also requires an external package). At the time
I added CSS/themes customization support to the build system, this was the only
theme that allowed to switch to either dark/light mode. It would be really cool
if Alabaster (or some other default themes) could honor the user's preference
between light/dark modes.
Regards,
Mauro
Mauro Carvalho Chehab <[email protected]> writes:
> I would play with the sidebar options used by Alabaster in order to
> try to make the TOC more useful.
Definitely worth doing; I'm not sure how much flexibility there is
there.
I'd *really* like to avoid carrying our own theme if at all possible...
The right solution might be to actually split the books apart and do the
intersphinx thing; I've not really looked into that at all.
> On a side note, one thing I miss on all default themes is a way to dynamically
> use dark mode. That's btw why I ended adding non-default support for
> 'sphinx_rtd_dark_mode' (which also requires an external package). At the time
> I added CSS/themes customization support to the build system, this was the only
> theme that allowed to switch to either dark/light mode. It would be really cool
> if Alabaster (or some other default themes) could honor the user's preference
> between light/dark modes.
Yeah, Alabaster doesn't seem to have that. Providing that ability in
conf.py shouldn't be *that* hard to do; it doesn't use that many colors,
though there might be a fair amount of CSS to override.
Thanks,
jon
On Tue, 04 Oct 2022, Jonathan Corbet <[email protected]> wrote:
> The read-the-docs theme is not entirely attractive and doesn't give us
> control over the left column. "Alabaster" is deemed the default Sphinx
> theme, it is currently maintained and shipped bundled with Sphinx itself,
> so there is no need to install it separately. Switch over to this theme as
> the default for building kernel documentation; the DOCS_THEME environment
> variable can still be used to select a different theme.
>
> Signed-off-by: Jonathan Corbet <[email protected]>
> ---
> Documentation/conf.py | 26 ++++++++++++++++++++++++--
> 1 file changed, 24 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 22c9d4df1967..629f4afeb0eb 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -194,6 +194,24 @@ finally:
> else:
> version = release = "unknown version"
>
> +#
> +# HACK: there seems to be no easy way for us to get at the version and
> +# release information passed in from the makefile...so go pawing through the
> +# command-line options and find it for ourselves.
> +#
> +def get_cline_version():
> + c_version = c_release = ''
> + for arg in sys.argv:
> + if arg.startswith('version='):
> + c_version = arg[8:]
> + elif arg.startswith('release='):
> + c_release = arg[8:]
> + if c_version:
> + if c_release:
> + return c_version + '-' + c_release
> + return c_version
> + return version # Whatever we came up with before
> +
This is a bit sad. There should be a way to set the description in the
theme template at a later time, when version is available. This is how
the rtd theme does it [1].
Would only need to inject one line in the template html, but I don't
know how to do that. :(
I wonder if the right way to do this would be to define our own theme,
which would mostly just extend alabaster, but would have small tweaks
[2]. Where are the Jinja experts when you need one?!
BR,
Jani.
[1] https://github.com/readthedocs/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/layout.html#L150
[2] https://www.sphinx-doc.org/en/master/templating.html
> # The language for content autogenerated by Sphinx. Refer to documentation
> # for a list of supported languages.
> #
> @@ -247,7 +265,7 @@ highlight_language = 'none'
> # a list of builtin themes.
>
> # Default theme
> -html_theme = 'sphinx_rtd_theme'
> +html_theme = 'alabaster'
> html_css_files = []
>
> if "DOCS_THEME" in os.environ:
> @@ -324,6 +342,10 @@ if html_theme == 'classic':
> 'bodyfont': "serif",
> 'headfont': "sans-serif",
> }
> +else:
> + html_theme_options = {
> + 'description': get_cline_version(),
> + }
>
> sys.stderr.write("Using %s theme\n" % html_theme)
>
> @@ -371,7 +393,7 @@ html_use_smartypants = False
>
> # Custom sidebar templates, maps document names to template names.
> # Note that the RTD theme ignores this
> -html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']}
> +html_sidebars = { '**': ["about.html", 'searchbox.html', 'localtoc.html', 'sourcelink.html']}
>
> # Additional templates that should be rendered to pages, maps page names to
> # template names.
--
Jani Nikula, Intel Open Source Graphics Center
Jani Nikula <[email protected]> writes:
> I wonder if the right way to do this would be to define our own theme,
> which would mostly just extend alabaster, but would have small tweaks
> [2]. Where are the Jinja experts when you need one?!
>
> [2] https://www.sphinx-doc.org/en/master/templating.html
I've pondered just creating our own theme, it's not *that* hard to do.
It's another thing to maintain across multiple sphinx versions, though.
I'd be more enthusiastic about the idea if we had a $SOMEBODY who would
commit to doing that.
Thanks,
jon
Em Wed, 05 Oct 2022 09:33:16 -0600
Jonathan Corbet <[email protected]> escreveu:
> Mauro Carvalho Chehab <[email protected]> writes:
>
> > I would play with the sidebar options used by Alabaster in order to
> > try to make the TOC more useful.
>
> Definitely worth doing; I'm not sure how much flexibility there is
> there.
>
> I'd *really* like to avoid carrying our own theme if at all possible...
Yeah, agreed.
Btw right now if you don't have RTD installed, it will already fallback to
classic Sphinx-native theme, on a non-optimized way, as it will be using the
CSS wrote for RTD.
> The right solution might be to actually split the books apart and do the
> intersphinx thing; I've not really looked into that at all.
Yeah, we've been postponing using intersphinx for quite a while. Perhaps
we could start supporting it. One expected advantage would be to make
life easier when building just a single book, as intersphinx should keep
the cross-references working and it should not produce extra warnings due
to references that belong to other books.
> > On a side note, one thing I miss on all default themes is a way to dynamically
> > use dark mode. That's btw why I ended adding non-default support for
> > 'sphinx_rtd_dark_mode' (which also requires an external package). At the time
> > I added CSS/themes customization support to the build system, this was the only
> > theme that allowed to switch to either dark/light mode. It would be really cool
> > if Alabaster (or some other default themes) could honor the user's preference
> > between light/dark modes.
>
> Yeah, Alabaster doesn't seem to have that. Providing that ability in
> conf.py shouldn't be *that* hard to do; it doesn't use that many colors,
> though there might be a fair amount of CSS to override.
RTD dark mode [1] solves it in runtime using a CSS with:
html[data-theme='dark'] body {
color: #bfbfbf;
}
A JS sets "data-theme" to dark in order to activate it in runtime[1] with:
document.documentElement.setAttribute('data-theme', 'dark');
It also comes with a .py file that selects the default.
But yeah, there are a fair amount of CSS to override.
Also, I suspect that maintaining it can be a challenge. Not sure if it
worth the efforts.
[1] https://github.com/MrDogeBro/sphinx_rtd_dark_mode/tree/main/sphinx_rtd_dark_mode
Regards,
Mauro
Em Wed, 05 Oct 2022 11:49:33 -0600
Jonathan Corbet <[email protected]> escreveu:
> Jani Nikula <[email protected]> writes:
>
> > I wonder if the right way to do this would be to define our own theme,
> > which would mostly just extend alabaster, but would have small tweaks
> > [2]. Where are the Jinja experts when you need one?!
> >
> > [2] https://www.sphinx-doc.org/en/master/templating.html
>
> I've pondered just creating our own theme, it's not *that* hard to do.
> It's another thing to maintain across multiple sphinx versions, though.
Yeah, that can be painful. Btw, at least on Fedora, RTD dark theme is
not working anymore (perhaps because Python 3.10 - the extension announces
it up to python 3.9).
I suspect that maintaining our own theme will require extra efforts to
workaround with per-version ABIs that keep changing on both Python and
Sphinx sides.
> I'd be more enthusiastic about the idea if we had a $SOMEBODY who would
> commit to doing that.
>
> Thanks,
>
> jon
Em Tue, 4 Oct 2022 14:12:18 -0600
Jonathan Corbet <[email protected]> escreveu:
> The read-the-docs theme is not entirely attractive and doesn't give us
> control over the left column. "Alabaster" is deemed the default Sphinx
> theme, it is currently maintained and shipped bundled with Sphinx itself,
> so there is no need to install it separately. Switch over to this theme as
> the default for building kernel documentation; the DOCS_THEME environment
> variable can still be used to select a different theme.
>
> Signed-off-by: Jonathan Corbet <[email protected]>
> ---
> Documentation/conf.py | 26 ++++++++++++++++++++++++--
> 1 file changed, 24 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 22c9d4df1967..629f4afeb0eb 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -194,6 +194,24 @@ finally:
> else:
> version = release = "unknown version"
>
> +#
> +# HACK: there seems to be no easy way for us to get at the version and
> +# release information passed in from the makefile...so go pawing through the
> +# command-line options and find it for ourselves.
> +#
> +def get_cline_version():
> + c_version = c_release = ''
> + for arg in sys.argv:
> + if arg.startswith('version='):
> + c_version = arg[8:]
> + elif arg.startswith('release='):
> + c_release = arg[8:]
> + if c_version:
> + if c_release:
> + return c_version + '-' + c_release
> + return c_version
> + return version # Whatever we came up with before
> +
> # The language for content autogenerated by Sphinx. Refer to documentation
> # for a list of supported languages.
> #
> @@ -247,7 +265,7 @@ highlight_language = 'none'
> # a list of builtin themes.
>
> # Default theme
> -html_theme = 'sphinx_rtd_theme'
> +html_theme = 'alabaster'
> html_css_files = []
You should probably touch other parts of conf.py as well, folding your
patch 1 with the enclosed diff - or some variant of it.
Basically, the current logic is to try RTD. If not found, fall back to
classic (which is also a native theme), customizing it a little bit to
look closer to the way RTD outputs the sidebars, and adjusting some colors
to make it look nicer.
Regards,
Mauro
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 934727e23e0e..87f821287908 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -241,7 +241,7 @@ if html_theme == 'sphinx_rtd_theme' or html_theme == 'sphinx_rtd_dark_mode':
html_css_files.append('theme_rtd_colors.css')
except ImportError:
- html_theme = 'classic'
+ html_theme = 'alabaster'
if "DOCS_CSS" in os.environ:
css = os.environ["DOCS_CSS"].split(" ")
@@ -257,36 +257,6 @@ if major <= 1 and minor < 8:
for l in html_css_files:
html_context['css_files'].append('_static/' + l)
-if html_theme == 'classic':
- html_theme_options = {
- 'rightsidebar': False,
- 'stickysidebar': True,
- 'collapsiblesidebar': True,
- 'externalrefs': False,
-
- 'footerbgcolor': "white",
- 'footertextcolor': "white",
- 'sidebarbgcolor': "white",
- 'sidebarbtncolor': "black",
- 'sidebartextcolor': "black",
- 'sidebarlinkcolor': "#686bff",
- 'relbarbgcolor': "#133f52",
- 'relbartextcolor': "white",
- 'relbarlinkcolor': "white",
- 'bgcolor': "white",
- 'textcolor': "black",
- 'headbgcolor': "#f2f2f2",
- 'headtextcolor': "#20435c",
- 'headlinkcolor': "#c60f0f",
- 'linkcolor': "#355f7c",
- 'visitedlinkcolor': "#355f7c",
- 'codebgcolor': "#3f3f3f",
- 'codetextcolor': "white",
-
- 'bodyfont': "serif",
- 'headfont': "sans-serif",
- }
-
sys.stderr.write("Using %s theme\n" % html_theme)
# Theme options are theme-specific and customize the look and feel of a theme
On Tue, 04 Oct 2022, Jonathan Corbet <[email protected]> wrote:
> For a long time we have rejoiced that our HTML output from Sphinx is far
> better than what we got from the old DocBook toolchain. But it still
> leaves a lot to be desired; the following is an attempt to improve the
> situation somewhat.
>
> Sphinx has a theming mechanism for HTML rendering. Since the kernel's
> adoption of Sphinx, we have been using the "Read The Docs" theme — a choice
> made in a bit of a hurry to have *something* while figuring out the rest.
> RTD is OK, but it is not hugely attractive, requires the installation of an
> extra package, and does not observe all of the Sphinx configuration
> parameters. Among other things, that makes it hard to put reasonable
> contents into the left column in the HTML output.
>
> The Alabaster theme is the default for Sphinx installations, and is bundled
> with Sphinx itself. It has (IMO) nicer output and gives us the control
> that we need.
>
> So: switch to Alabaster. Additional patches adjust the documentation and
> remove the RTD references from scripts/sphinx-pre-install.
>
> The final patch changes the way that kerneldoc declarations are rendered to
> (IMO) improve readability. That requires some changes to kernel-doc to
> output a new container block and some CSS tweaks to improve things overall.
>
> It should be noted that I have a long history of inflicting ugly web
> designs on the net; this work is a start, but I think we could do far
> better yet. It would be great if somebody who actually enjoys working with
> CSS and such would help to improve what we have.
I admit my wish-list replies to this thread may seem a bit obnoxious,
when I'm not prepared to contribute. Sorry about that. My intention was
not to block any of this, rather muse about what the future direction
might be.
Overall I think this is an improvement.
There's only two things that I'd like to get addressed, not necessarily
now, but eventually:
- As mentioned, the main div width as pixels in the alabaster
theme. It's really crappy on wide 4K displays. Only a quarter of the
full screen width is used.
- The function/struct/etc. main descriptions are now displayed in the
gray background, along with the "declaration", instead of white
background. Is that an intenational alabaster feature, or is it
something we do to cause that? Seems like the description gets a bit
hidden there.
BR,
Jani.
>
> As before, I've put a copy of the rendered docs at:
>
> https://static.lwn.net/kerneldoc/
>
> To compare the kerneldoc changes specifically, pick a page that includes a
> lot of definitions; for example:
>
> https://static.lwn.net/kerneldoc/driver-api/media/drivers/frontends.html
> vs.
> https://www.kernel.org/doc/html/latest/driver-api/media/drivers/frontends.html
>
> Jonathan Corbet (5):
> docs: Switch the default HTML theme to alabaster
> docs: tweak some Alabaster style parameters
> docs: update sphinx.rst to reflect the default theme change
> docs: sphinx-pre-install: don't require the RTD theme
> docs: improve the HTML formatting of kerneldoc comments
>
> Documentation/conf.py | 27 ++++++++++++-
> Documentation/doc-guide/sphinx.rst | 16 +++-----
> Documentation/sphinx-static/custom.css | 25 +++++++++++++
> Documentation/sphinx/requirements.txt | 1 -
> scripts/kernel-doc | 52 ++++++++++++++++----------
> scripts/sphinx-pre-install | 8 ----
> 6 files changed, 87 insertions(+), 42 deletions(-)
> create mode 100644 Documentation/sphinx-static/custom.css
--
Jani Nikula, Intel Open Source Graphics Center
Jani Nikula <[email protected]> writes:
> I admit my wish-list replies to this thread may seem a bit obnoxious,
> when I'm not prepared to contribute. Sorry about that. My intention was
> not to block any of this, rather muse about what the future direction
> might be.
Wish lists are good. As noted before, if we're depending on me to come
up with the web design, we're in trouble...
> Overall I think this is an improvement.
>
> There's only two things that I'd like to get addressed, not necessarily
> now, but eventually:
>
> - As mentioned, the main div width as pixels in the alabaster
> theme. It's really crappy on wide 4K displays. Only a quarter of the
> full screen width is used.
>
> - The function/struct/etc. main descriptions are now displayed in the
> gray background, along with the "declaration", instead of white
> background. Is that an intenational alabaster feature, or is it
> something we do to cause that? Seems like the description gets a bit
> hidden there.
Both of these should be relatively easily done with CSS overrides, I'll
look into it.
jon