[PATCH v2 0/6] docs: Improvements to our HTML output

[PATCH v2 0/6] docs: Improvements to our HTML output

[Jonathan Corbet]

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

[PATCH v2 1/6] docs: Switch the default HTML theme to alabaster

[Jonathan Corbet]

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 <corbet@lwn.net>
---
 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

[PATCH v2 2/6] docs: tweak some Alabaster style parameters

[Jonathan Corbet]

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 <corbet@lwn.net>
---
 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

[PATCH v2 3/6] docs: update sphinx.rst to reflect the default theme change

[Jonathan Corbet]

We don't default to Read The Docs anymore; update the docs to match.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/doc-guide/sphinx.rst | 16 +++++-----------
 1 file changed, 5 insertions(+), 11 deletions(-)

diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 1228b85f6f77..d71e0beb11f3 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -130,11 +130,9 @@ section of ``make help``. The generated documentation is placed in
 format-specific subdirectories under ``Documentation/output``.
 
 To generate documentation, Sphinx (``sphinx-build``) must obviously be
-installed. For prettier HTML output, the Read the Docs Sphinx theme
-(``sphinx_rtd_theme``) is used if available. For PDF output you'll also need
-``XeLaTeX`` and ``convert(1)`` from ImageMagick
-(https://www.imagemagick.org).\ [#ink]_
-All of these are widely available and packaged in distributions.
+installed.  For PDF output you'll also need ``XeLaTeX`` and ``convert(1)``
+from ImageMagick (https://www.imagemagick.org).\ [#ink]_ All of these are
+widely available and packaged in distributions.
 
 To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
 variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
@@ -143,12 +141,8 @@ output.
 It is also possible to pass an extra DOCS_CSS overlay file, in order to customize
 the html layout, by using the ``DOCS_CSS`` make variable.
 
-By default, the build will try to use the Read the Docs sphinx theme:
-
-    https://github.com/readthedocs/sphinx_rtd_theme
-
-If the theme is not available, it will fall-back to the classic one.
-
+By default, the "Alabaster" theme is used to build the HTML documentation;
+this theme is bundled with Sphinx and need not be installed separately.
 The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable.
 
 There is another make variable ``SPHINXDIRS``, which is useful when test
-- 
2.37.2

[PATCH v2 4/6] docs: sphinx-pre-install: don't require the RTD theme

[Jonathan Corbet]

We don't default to the RTD theme anymore, so sphinx-pre-install need not
insist on installing it.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 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

[PATCH v2 5/6] docs: improve the HTML formatting of kerneldoc comments

[Jonathan Corbet]

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 <corbet@lwn.net>
---
 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

[PATCH v2 6/6] docs: decruft Documentation/conf.py

[Jonathan Corbet]

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 <mchehab@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 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

Re: [PATCH v2 0/6] docs: Improvements to our HTML output

[Mauro Carvalho Chehab]

Em Tue, 11 Oct 2022 13:00:41 -0600
Jonathan Corbet <corbet@lwn.net> 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 <mchehab@kernel.org>

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
> 

Re: [PATCH v2 0/6] docs: Improvements to our HTML output

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab@kernel.org> 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

Re: [PATCH v2 0/6] docs: Improvements to our HTML output

[Bagas Sanjaya]

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

Re: [PATCH v2 0/6] docs: Improvements to our HTML output

[Randy Dunlap]

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 <corbet@lwn.net>
L:	linux-doc@vger.kernel.org
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

Re: [PATCH v2 0/6] docs: Improvements to our HTML output

[Bagas Sanjaya]

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 <corbet@lwn.net>
> L:	linux-doc@vger.kernel.org
> 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

Re: [PATCH v2 0/6] docs: Improvements to our HTML output

[Jonathan Corbet]

Bagas Sanjaya <bagasdotme@gmail.com> 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

Re: [PATCH v2 0/6] docs: Improvements to our HTML output

[Akira Yokosawa]

Hi Jon,

On Wed, 12 Oct 2022 06:38:51 -0600, Jonathan Corbet wrote:
> Bagas Sanjaya <bagasdotme@gmail.com> 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

Re: [PATCH v2 0/6] docs: Improvements to our HTML output

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> 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