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 penultimate 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
-------
Changes from the initial version:
- Tweak more alabaster style parameters, including the maximum page width.
There will surely be disagreement over what the right value should be,
but at least it's defined in units independent of screen resolution.
- Remove "classic" theme configuration and a bunch of other conf.py cruft.
- I've tried to answer all of the other comments, but a couple remain. The
sidebar contents are unchanged; making that more useful will require some
thought and work. The gray background on function prototypes that Jani
pointed out is actually something I did intentionally, with the idea of
making each declaration stand out better in the wall of text. I still
think it's better but am not married to it if the world disagrees.
- I've tested PDF and epub builds (no changes) and Sphinx back to v1.7.
In the absence of objections I'll be putting this into docs-next after the
merge window closes. We can (and surely will) tweak this forever, but at
least it, I hope, shows a direction in which we can go.
Jonathan Corbet (6):
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
docs: decruft Documentation/conf.py
Documentation/conf.py | 204 ++++---------------------
Documentation/doc-guide/sphinx.rst | 16 +-
Documentation/sphinx-static/custom.css | 28 ++++
Documentation/sphinx/requirements.txt | 1 -
scripts/kernel-doc | 52 ++++---
scripts/sphinx-pre-install | 8 -
6 files changed, 91 insertions(+), 218 deletions(-)
create mode 100644 Documentation/sphinx-static/custom.css
--
2.37.2
Remove the ancient support for the Sphinx "classic" theme; everybody will
have alabaster, so that fallback is no longer needed.
While in the neighborhood: get rid of lots of useless comment lines. They
describe the state of Sphinx options when we first created that file and
are just clutter now.
Suggested-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
---
Documentation/conf.py | 181 +-----------------------------------------
1 file changed, 2 insertions(+), 179 deletions(-)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 1dbf3d6a55de..6ab47833ab6c 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -297,7 +297,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(" ")
@@ -313,36 +313,7 @@ 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",
- }
-else:
+if html_theme == 'alabaster':
html_theme_options = {
'description': get_cline_version(),
'font_size': '10pt',
@@ -352,44 +323,11 @@ else:
sys.stderr.write("Using %s theme\n" % html_theme)
-# Theme options are theme-specific and customize the look and feel of a theme
-# further. For a list of options available for each theme, see the
-# documentation.
-#html_theme_options = {}
-
-# Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
-
-# The name for this set of Sphinx documents. If None, it defaults to
-# "<project> v<release> documentation".
-#html_title = None
-
-# A shorter title for the navigation bar. Default is the same as html_title.
-#html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#html_logo = None
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
-
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['sphinx-static']
-# Add any extra paths that contain custom files (such as robots.txt or
-# .htaccess) here, relative to this directory. These files are copied
-# directly to the root of the documentation.
-#html_extra_path = []
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
-
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
html_use_smartypants = False
@@ -398,50 +336,6 @@ html_use_smartypants = False
# Note that the RTD theme ignores this
html_sidebars = { '**': ["about.html", 'searchbox.html', 'localtoc.html', 'sourcelink.html']}
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#html_additional_pages = {}
-
-# If false, no module index is generated.
-#html_domain_indices = True
-
-# If false, no index is generated.
-#html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
-
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it. The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = None
-
-# Language to be used for generating the HTML full-text search index.
-# Sphinx supports the following languages:
-# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
-# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
-#html_search_language = 'en'
-
-# A dictionary with options for the search language support, empty by default.
-# Now only 'ja' uses this config value
-#html_search_options = {'type': 'default'}
-
-# The name of a javascript file (relative to the configuration directory) that
-# implements a search results scorer. If empty, the default will be used.
-#html_search_scorer = 'scorer.js'
-
# Output file base name for HTML help builder.
htmlhelp_basename = 'TheLinuxKerneldoc'
@@ -583,19 +477,6 @@ texinfo_documents = [
'Miscellaneous'),
]
-# Documents to append as an appendix to all manuals.
-#texinfo_appendices = []
-
-# If false, no module index is generated.
-#texinfo_domain_indices = True
-
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#texinfo_show_urls = 'footnote'
-
-# If true, do not generate a @detailmenu in the "Top" node's menu.
-#texinfo_no_detailmenu = False
-
-
# -- Options for Epub output ----------------------------------------------
# Bibliographic Dublin Core info.
@@ -604,67 +485,9 @@ epub_author = author
epub_publisher = author
epub_copyright = copyright
-# The basename for the epub file. It defaults to the project name.
-#epub_basename = project
-
-# The HTML theme for the epub output. Since the default themes are not
-# optimized for small screen space, using the same theme for HTML and epub
-# output is usually not wise. This defaults to 'epub', a theme designed to save
-# visual space.
-#epub_theme = 'epub'
-
-# The language of the text. It defaults to the language option
-# or 'en' if the language is not set.
-#epub_language = ''
-
-# The scheme of the identifier. Typical schemes are ISBN or URL.
-#epub_scheme = ''
-
-# The unique identifier of the text. This can be a ISBN number
-# or the project homepage.
-#epub_identifier = ''
-
-# A unique identification for the text.
-#epub_uid = ''
-
-# A tuple containing the cover image and cover page html template filenames.
-#epub_cover = ()
-
-# A sequence of (type, uri, title) tuples for the guide element of content.opf.
-#epub_guide = ()
-
-# HTML files that should be inserted before the pages created by sphinx.
-# The format is a list of tuples containing the path and title.
-#epub_pre_files = []
-
-# HTML files that should be inserted after the pages created by sphinx.
-# The format is a list of tuples containing the path and title.
-#epub_post_files = []
-
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
-# The depth of the table of contents in toc.ncx.
-#epub_tocdepth = 3
-
-# Allow duplicate toc entries.
-#epub_tocdup = True
-
-# Choose between 'default' and 'includehidden'.
-#epub_tocscope = 'default'
-
-# Fix unsupported image types using the Pillow.
-#epub_fix_images = False
-
-# Scale large images.
-#epub_max_image_width = 0
-
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#epub_show_urls = 'inline'
-
-# If false, no index is generated.
-#epub_use_index = True
-
#=======
# rst2pdf
#
--
2.37.2
This is just the beginning: tighten up the layout a bit to improve the
information density in the browser. Also reconfigure the page width in
terms of character units (em) rather than pixels, making it more
display-independent. To that end, add a custom.css file to
tweak Alabaster CSS settings.
Signed-off-by: Jonathan Corbet <[email protected]>
---
Documentation/conf.py | 3 +++
Documentation/sphinx-static/custom.css | 14 ++++++++++++++
2 files changed, 17 insertions(+)
create mode 100644 Documentation/sphinx-static/custom.css
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 629f4afeb0eb..1dbf3d6a55de 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -345,6 +345,9 @@ if html_theme == 'classic':
else:
html_theme_options = {
'description': get_cline_version(),
+ 'font_size': '10pt',
+ 'page_width': '65em',
+ 'sidebar_width': '15em',
}
sys.stderr.write("Using %s theme\n" % html_theme)
diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
new file mode 100644
index 000000000000..6b0e554cea0a
--- /dev/null
+++ b/Documentation/sphinx-static/custom.css
@@ -0,0 +1,14 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+/*
+ * CSS tweaks for the Alabaster theme
+ */
+
+/* Shrink the headers a bit */
+div.body h1 { font-size: 180%; }
+div.body h2 { font-size: 150%; }
+div.body h3 { font-size: 130%; }
+
+/* Tighten up the layout slightly */
+div.body { padding: 0 15px 0 10px; }
+div.document { margin: 20px 10px 0 10px; }
+div.sphinxsidebarwrapper { padding: 1em 0.4em; }
--
2.37.2
Make a few changes to cause functions documented by kerneldoc to stand out
better in the rendered documentation. Specifically, change kernel-doc to
put the description section into a ".. container::" section, then add a bit
of CSS to indent that section relative to the function prototype (or struct
or enum definition). Tweak a few other CSS parameters while in the
neighborhood to improve the formatting.
Signed-off-by: Jonathan Corbet <[email protected]>
---
Documentation/sphinx-static/custom.css | 16 +++++++-
scripts/kernel-doc | 52 ++++++++++++++++----------
2 files changed, 47 insertions(+), 21 deletions(-)
diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index 6b0e554cea0a..9b36f7abd24f 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -10,5 +10,19 @@ div.body h3 { font-size: 130%; }
/* Tighten up the layout slightly */
div.body { padding: 0 15px 0 10px; }
-div.document { margin: 20px 10px 0 10px; }
div.sphinxsidebarwrapper { padding: 1em 0.4em; }
+/* Tweak document margins and don't force width */
+div.document {
+ margin: 20px 10px 0 10px;
+ width: auto;
+}
+
+/*
+ * Parameters for the display of function prototypes and such included
+ * from C source files.
+ */
+dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; }
+/* indent lines 2+ of multi-line function prototypes */
+dl.function dt { margin-left: 10em; text-indent: -10em; }
+dt.sig-object { font-size: larger; }
+div.kernelindent { margin-left: 2em; margin-right: 4em; }
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index aea04365bc69..85ea80fb5154 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -866,48 +866,53 @@ sub output_function_rst(%) {
print "\n";
}
- print "**Parameters**\n\n";
+ #
+ # Put our descriptive text into a container (thus an HTML <div>) to help
+ # set the function prototypes apart.
+ #
+ print ".. container:: kernelindent\n\n";
$lineprefix = " ";
+ print $lineprefix . "**Parameters**\n\n";
foreach $parameter (@{$args{'parameterlist'}}) {
my $parameter_name = $parameter;
$parameter_name =~ s/\[.*//;
$type = $args{'parametertypes'}{$parameter};
if ($type ne "") {
- print "``$type``\n";
+ print $lineprefix . "``$type``\n";
} else {
- print "``$parameter``\n";
+ print $lineprefix . "``$parameter``\n";
}
print_lineno($parameterdesc_start_lines{$parameter_name});
+ $lineprefix = " ";
if (defined($args{'parameterdescs'}{$parameter_name}) &&
$args{'parameterdescs'}{$parameter_name} ne $undescribed) {
output_highlight_rst($args{'parameterdescs'}{$parameter_name});
} else {
- print " *undescribed*\n";
+ print $lineprefix . "*undescribed*\n";
}
+ $lineprefix = " ";
print "\n";
}
- $lineprefix = $oldprefix;
output_section_rst(@_);
+ $lineprefix = $oldprefix;
}
sub output_section_rst(%) {
my %args = %{$_[0]};
my $section;
my $oldprefix = $lineprefix;
- $lineprefix = "";
foreach $section (@{$args{'sectionlist'}}) {
- print "**$section**\n\n";
+ print $lineprefix . "**$section**\n\n";
print_lineno($section_start_lines{$section});
output_highlight_rst($args{'sections'}{$section});
print "\n";
}
print "\n";
- $lineprefix = $oldprefix;
}
sub output_enum_rst(%) {
@@ -915,6 +920,7 @@ sub output_enum_rst(%) {
my ($parameter);
my $oldprefix = $lineprefix;
my $count;
+ my $outer;
if ($sphinx_major < 3) {
my $name = "enum " . $args{'enum'};
@@ -924,14 +930,17 @@ sub output_enum_rst(%) {
print "\n\n.. c:enum:: " . $name . "\n\n";
}
print_lineno($declaration_start_line);
- $lineprefix = " ";
+ $lineprefix = " ";
output_highlight_rst($args{'purpose'});
print "\n";
- print "**Constants**\n\n";
- $lineprefix = " ";
+ print ".. container:: kernelindent\n\n";
+ $outer = $lineprefix . " ";
+ $lineprefix = $outer . " ";
+ print $outer . "**Constants**\n\n";
foreach $parameter (@{$args{'parameterlist'}}) {
- print "``$parameter``\n";
+ print $outer . "``$parameter``\n";
+
if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
output_highlight_rst($args{'parameterdescs'}{$parameter});
} else {
@@ -939,7 +948,7 @@ sub output_enum_rst(%) {
}
print "\n";
}
-
+ print "\n";
$lineprefix = $oldprefix;
output_section_rst(@_);
}
@@ -982,18 +991,19 @@ sub output_struct_rst(%) {
}
}
print_lineno($declaration_start_line);
- $lineprefix = " ";
+ $lineprefix = " ";
output_highlight_rst($args{'purpose'});
print "\n";
- print "**Definition**\n\n";
- print "::\n\n";
+ print ".. container:: kernelindent\n\n";
+ print $lineprefix . "**Definition**::\n\n";
my $declaration = $args{'definition'};
- $declaration =~ s/\t/ /g;
- print " " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration };\n\n";
+ $lineprefix = $lineprefix . " ";
+ $declaration =~ s/\t/$lineprefix/g;
+ print $lineprefix . $args{'type'} . " " . $args{'struct'} . " {\n$declaration" . $lineprefix . "};\n\n";
- print "**Members**\n\n";
$lineprefix = " ";
+ print $lineprefix . "**Members**\n\n";
foreach $parameter (@{$args{'parameterlist'}}) {
($parameter =~ /^#/) && next;
@@ -1003,8 +1013,10 @@ sub output_struct_rst(%) {
($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
$type = $args{'parametertypes'}{$parameter};
print_lineno($parameterdesc_start_lines{$parameter_name});
- print "``" . $parameter . "``\n";
+ print $lineprefix . "``" . $parameter . "``\n";
+ $lineprefix = " ";
output_highlight_rst($args{'parameterdescs'}{$parameter_name});
+ $lineprefix = " ";
print "\n";
}
print "\n";
--
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
Em Tue, 11 Oct 2022 13:00:41 -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.
>
> So: switch to Alabaster. Additional patches adjust the documentation and
> remove the RTD references from scripts/sphinx-pre-install.
>
> The penultimate 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
>
> -------
> Changes from the initial version:
>
> - Tweak more alabaster style parameters, including the maximum page width.
> There will surely be disagreement over what the right value should be,
> but at least it's defined in units independent of screen resolution.
>
> - Remove "classic" theme configuration and a bunch of other conf.py cruft.
>
> - I've tried to answer all of the other comments, but a couple remain. The
> sidebar contents are unchanged; making that more useful will require some
> thought and work. The gray background on function prototypes that Jani
> pointed out is actually something I did intentionally, with the idea of
> making each declaration stand out better in the wall of text. I still
> think it's better but am not married to it if the world disagrees.
>
> - I've tested PDF and epub builds (no changes) and Sphinx back to v1.7.
>
> In the absence of objections I'll be putting this into docs-next after the
> merge window closes. We can (and surely will) tweak this forever, but at
> least it, I hope, shows a direction in which we can go.
No objections from my side. Surely more things could be tweaked. In
particular, I didn't like having two ToCs at the index (a complete one
and a second one pointing to where we are at the docs), but that's a lot
better than before, so, I'm OK with that.
Feel free to add my ack to the patches:
Acked-by: Mauro Carvalho Chehab <[email protected]>
Regards,
Mauro
>
> Jonathan Corbet (6):
> 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
> docs: decruft Documentation/conf.py
>
> Documentation/conf.py | 204 ++++---------------------
> Documentation/doc-guide/sphinx.rst | 16 +-
> Documentation/sphinx-static/custom.css | 28 ++++
> Documentation/sphinx/requirements.txt | 1 -
> scripts/kernel-doc | 52 ++++---
> scripts/sphinx-pre-install | 8 -
> 6 files changed, 91 insertions(+), 218 deletions(-)
> create mode 100644 Documentation/sphinx-static/custom.css
>
Mauro Carvalho Chehab <[email protected]> writes:
> No objections from my side. Surely more things could be tweaked. In
> particular, I didn't like having two ToCs at the index (a complete one
> and a second one pointing to where we are at the docs), but that's a lot
> better than before, so, I'm OK with that.
Oops...that was actually a leftover from my initial attempts to improve
the information there. That's not what the patches create...I've
updated the rendered docs to reflect the actual output.
Sorry for the confusion,
jon
On 10/12/22 02:00, Jonathan Corbet 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 penultimate 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
>
> -------
> Changes from the initial version:
>
> - Tweak more alabaster style parameters, including the maximum page width.
> There will surely be disagreement over what the right value should be,
> but at least it's defined in units independent of screen resolution.
>
> - Remove "classic" theme configuration and a bunch of other conf.py cruft.
>
> - I've tried to answer all of the other comments, but a couple remain. The
> sidebar contents are unchanged; making that more useful will require some
> thought and work. The gray background on function prototypes that Jani
> pointed out is actually something I did intentionally, with the idea of
> making each declaration stand out better in the wall of text. I still
> think it's better but am not married to it if the world disagrees.
>
> - I've tested PDF and epub builds (no changes) and Sphinx back to v1.7.
>
> In the absence of objections I'll be putting this into docs-next after the
> merge window closes. We can (and surely will) tweak this forever, but at
> least it, I hope, shows a direction in which we can go.
>
Hmm, I can't cleanly apply this patch series on top of either Linus's tree
or linux-next due to conflicts on [1/6]. On what commit this series is based
on?
--
An old man doll... just what I always wanted! - Clara
On 10/11/22 19:10, Bagas Sanjaya wrote:
> On 10/12/22 02:00, Jonathan Corbet 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 penultimate 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
>>
>> -------
>> Changes from the initial version:
>>
>> - Tweak more alabaster style parameters, including the maximum page width.
>> There will surely be disagreement over what the right value should be,
>> but at least it's defined in units independent of screen resolution.
>>
>> - Remove "classic" theme configuration and a bunch of other conf.py cruft.
>>
>> - I've tried to answer all of the other comments, but a couple remain. The
>> sidebar contents are unchanged; making that more useful will require some
>> thought and work. The gray background on function prototypes that Jani
>> pointed out is actually something I did intentionally, with the idea of
>> making each declaration stand out better in the wall of text. I still
>> think it's better but am not married to it if the world disagrees.
>>
>> - I've tested PDF and epub builds (no changes) and Sphinx back to v1.7.
>>
>> In the absence of objections I'll be putting this into docs-next after the
>> merge window closes. We can (and surely will) tweak this forever, but at
>> least it, I hope, shows a direction in which we can go.
>>
>
> Hmm, I can't cleanly apply this patch series on top of either Linus's tree
> or linux-next due to conflicts on [1/6]. On what commit this series is based
> on?
Normally Jon uses this (from the MAINTAINERS file):
DOCUMENTATION
M: Jonathan Corbet <[email protected]>
L: [email protected]
S: Maintained
P: Documentation/doc-guide/maintainer-profile.rst
T: git git://git.lwn.net/linux.git docs-next
Did you try that one?
--
~Randy
On 10/12/22 09:25, Randy Dunlap wrote:
>> Hmm, I can't cleanly apply this patch series on top of either Linus's tree
>> or linux-next due to conflicts on [1/6]. On what commit this series is based
>> on?
>
> Normally Jon uses this (from the MAINTAINERS file):
>
> DOCUMENTATION
> M: Jonathan Corbet <[email protected]>
> L: [email protected]
> S: Maintained
> P: Documentation/doc-guide/maintainer-profile.rst
> T: git git://git.lwn.net/linux.git docs-next
>
>
> Did you try that one?
>
Hi Randy,
I can't fetch that repo (possibly blocked by my ISP), so I have to apply
against linux-next instead.
--
An old man doll... just what I always wanted! - Clara
Bagas Sanjaya <[email protected]> writes:
> Hmm, I can't cleanly apply this patch series on top of either Linus's tree
> or linux-next due to conflicts on [1/6]. On what commit this series is based
> on?
docs-next, which is still running off the pre-6.0 base until after the
merge window closes.
If I need to post another round before merging I'll drag everything
forward to a more current base.
Thanks,
jon
Hi Jon,
On Wed, 12 Oct 2022 06:38:51 -0600, Jonathan Corbet wrote:
> Bagas Sanjaya <[email protected]> writes:
>
>> Hmm, I can't cleanly apply this patch series on top of either Linus's tree
>> or linux-next due to conflicts on [1/6]. On what commit this series is based
>> on?
>
> docs-next, which is still running off the pre-6.0 base until after the
> merge window closes.
Hmm...
Actually, I can't apply 1/6 cleanly on docs-next, either.
As I have your tree in my local repo, "git am -3" worked and pointed
out there is a merge conflict.
It turns out that one of the hunks in 1/6 doesn't match what could be
applied cleanly.
[From 1/6]:
------------------------------------------------------
@@ -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.
------------------------------------------------------
What can be cleanly applied:
------------------------------------------------------
@@ -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.
------------------------------------------------------
There is an additional period at the comment of:
> # Note that the RTD theme ignores this.
^
So if you remove the period first, you should be able to apply the
patch set cleanly starting from docs-next or linux-next, I guess.
Sidenote: I see this warning when applying 5/6:
.git/rebase-apply/patch:18: trailing whitespace.
margin: 20px 10px 0 10px;
warning: 1 line adds whitespace errors.
Hope this helps.
Akira
>
> If I need to post another round before merging I'll drag everything
> forward to a more current base.
>
> Thanks,
>
> jon
Akira Yokosawa <[email protected]> writes:
> Actually, I can't apply 1/6 cleanly on docs-next, either.
> As I have your tree in my local repo, "git am -3" worked and pointed
> out there is a merge conflict.
>
> It turns out that one of the hunks in 1/6 doesn't match what could be
> applied cleanly.
OK, apologies...the branch that stuff is on was split out some time ago,
and I had to perform surgery on docs-next in the meantime. I should
have rebased it. I've done so now and will send a v3 to the list; I'll
try to avoid copying everybody again because there are no other changes.
Thanks,
jon