[PATCH RFC 0/5] docs: Improvements to our HTML output

[PATCH RFC 0/5] 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 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

[PATCH 1/5] 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

Re: [PATCH 1/5] docs: Switch the default HTML theme to alabaster

[Jani Nikula]

On Tue, 04 Oct 2022, Jonathan Corbet <corbet@lwn.net> 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 <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
> +

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

Re: [PATCH 1/5] docs: Switch the default HTML theme to alabaster

[Jonathan Corbet]

Jani Nikula <jani.nikula@linux.intel.com> 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

Re: [PATCH 1/5] docs: Switch the default HTML theme to alabaster

[Mauro Carvalho Chehab]

Em Wed, 05 Oct 2022 11:49:33 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Jani Nikula <jani.nikula@linux.intel.com> 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

Re: [PATCH 1/5] docs: Switch the default HTML theme to alabaster

[Mauro Carvalho Chehab]

Em Tue,  4 Oct 2022 14:12:18 -0600
Jonathan Corbet <corbet@lwn.net> 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 <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 = []

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

[PATCH 2/5] 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.  To that end, add a custom.css file to
tweak Alabaster CSS settings.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/conf.py                  |  1 +
 Documentation/sphinx-static/custom.css | 12 ++++++++++++
 2 files changed, 13 insertions(+)
 create mode 100644 Documentation/sphinx-static/custom.css

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 629f4afeb0eb..b924b266a70f 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -345,6 +345,7 @@ if  html_theme == 'classic':
 else:
     html_theme_options = {
         'description': get_cline_version(),
+        'font_size': '14px',
     }
 
 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..c465251e840a
--- /dev/null
+++ b/Documentation/sphinx-static/custom.css
@@ -0,0 +1,12 @@
+/* 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; }
-- 
2.37.2

Re: [PATCH 2/5] docs: tweak some Alabaster style parameters

[Jani Nikula]

On Tue, 04 Oct 2022, Jonathan Corbet <corbet@lwn.net> wrote:
> This is just the beginning: tighten up the layout a bit to improve the
> information density in the browser.  To that end, add a custom.css file to
> tweak Alabaster CSS settings.

Maybe it's just me, but on the wide 4K screen I have the page_width =
940px default is silly narrow.

BR,
Jani.



>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/conf.py                  |  1 +
>  Documentation/sphinx-static/custom.css | 12 ++++++++++++
>  2 files changed, 13 insertions(+)
>  create mode 100644 Documentation/sphinx-static/custom.css
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 629f4afeb0eb..b924b266a70f 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -345,6 +345,7 @@ if  html_theme == 'classic':
>  else:
>      html_theme_options = {
>          'description': get_cline_version(),
> +        'font_size': '14px',
>      }
>  
>  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..c465251e840a
> --- /dev/null
> +++ b/Documentation/sphinx-static/custom.css
> @@ -0,0 +1,12 @@
> +/* 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; }

-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [PATCH 2/5] docs: tweak some Alabaster style parameters

[Jonathan Corbet]

Jani Nikula <jani.nikula@linux.intel.com> writes:

> On Tue, 04 Oct 2022, Jonathan Corbet <corbet@lwn.net> wrote:
>> This is just the beginning: tighten up the layout a bit to improve the
>> information density in the browser.  To that end, add a custom.css file to
>> tweak Alabaster CSS settings.
>
> Maybe it's just me, but on the wide 4K screen I have the page_width =
> 940px default is silly narrow.

The real problem, of course, is defining things in terms of pixels to
begin with.  Redefining those things in resolution-independent units
(em, for example) would be an improvement.

When we get our CSS person to show up they can certainly fix that up for
us :)

Thanks,

jon

[PATCH 3/5] 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 4/5] 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 5/5] 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 | 13 +++++++
 scripts/kernel-doc                     | 52 ++++++++++++++++----------
 2 files changed, 45 insertions(+), 20 deletions(-)

diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index c465251e840a..d8823fbbd27b 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -10,3 +10,16 @@ div.body h3 { font-size: 130%; }
 
 /* Tighten up the layout slightly */
 div.body { padding: 0 15px 0 10px; }
+
+/* Don't force the document width */
+div.document { width: auto; max-width: 60em; }
+
+/*
+ * 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..13d42857bce2 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

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

[Mauro Carvalho Chehab]

Em Tue,  4 Oct 2022 14:12:22 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> 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 | 13 +++++++
>  scripts/kernel-doc                     | 52 ++++++++++++++++----------
>  2 files changed, 45 insertions(+), 20 deletions(-)
> 
> diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
> index c465251e840a..d8823fbbd27b 100644
> --- a/Documentation/sphinx-static/custom.css
> +++ b/Documentation/sphinx-static/custom.css
> @@ -10,3 +10,16 @@ div.body h3 { font-size: 130%; }
>  
>  /* Tighten up the layout slightly */
>  div.body { padding: 0 15px 0 10px; }
> +
> +/* Don't force the document width */
> +div.document { width: auto; max-width: 60em; }
> +
> +/*
> + * 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..13d42857bce2 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.

Nitpick: you forgot to close the parenthesis on your comment ;-)

> +    #
> +    print ".. container:: kernelindent\n\n";

I liked the new alignment: it makes easier to identify what belongs
to each definition block.

As I didn't test the patches, it sounds worth mentioning that it makes
sense to check if this won't badly affect epub and/or LaTeX/PDF outputs.

The LaTeX output generator in particular has a problem with long
lines with fixed-width lines: if the text doesn't fit into one line, it
either truncates it or makes the text go outside the margins.

If the container affects the PDF outputs, we need to double-check if
this would break its output.

Also, when the container directive was introduced? Does it affect
the minimal Sphinx version we support? It seems that this was old
enough to not require any changes at the minimal version, but,
from https://www.sphinx-doc.org/en/master/changes.html, it seems
that LaTeX support for it was added only at Sphinx v4.1 on this PR:

	https://github.com/sphinx-doc/sphinx/pull/9166

So, we need to double-check if are there any changes before and after
such version at the places container is used - or change the kerneldoc
to only emit such tags on PDF depending on the Sphinx version.

Regards,
Mauro

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

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab@kernel.org> writes:

> Nitpick: you forgot to close the parenthesis on your comment ;-)

Hey, I gotta provide something for people to complain about :)

>> +    #
>> +    print ".. container:: kernelindent\n\n";
>
> I liked the new alignment: it makes easier to identify what belongs
> to each definition block.
>
> As I didn't test the patches, it sounds worth mentioning that it makes
> sense to check if this won't badly affect epub and/or LaTeX/PDF outputs.
>
> The LaTeX output generator in particular has a problem with long
> lines with fixed-width lines: if the text doesn't fit into one line, it
> either truncates it or makes the text go outside the margins.
>
> If the container affects the PDF outputs, we need to double-check if
> this would break its output.

The __container:: directive is pretty much defined as contributing a
<div> do the HTML output, so I do not expect problems.  That said, I've
not yet tested it, and clearly need to.

> Also, when the container directive was introduced? Does it affect
> the minimal Sphinx version we support? It seems that this was old
> enough to not require any changes at the minimal version, but,
> from https://www.sphinx-doc.org/en/master/changes.html, it seems
> that LaTeX support for it was added only at Sphinx v4.1 on this PR:
>
> 	https://github.com/sphinx-doc/sphinx/pull/9166
>
> So, we need to double-check if are there any changes before and after
> such version at the places container is used - or change the kerneldoc
> to only emit such tags on PDF depending on the Sphinx version.

I've tested things as far back as 2.4.5, where all is well.  I don't
currently have a machine that is capable of running earlier versions;
I'll need to conjure one of those up, I guess.

(Either that or just bite the bullet and move the minimum version
forward!)

Thanks,

jon

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

[Mauro Carvalho Chehab]

Em Wed, 05 Oct 2022 09:29:45 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab@kernel.org> writes:

> > Also, when the container directive was introduced? Does it affect
> > the minimal Sphinx version we support? It seems that this was old
> > enough to not require any changes at the minimal version, but,
> > from https://www.sphinx-doc.org/en/master/changes.html, it seems
> > that LaTeX support for it was added only at Sphinx v4.1 on this PR:
> >
> > 	https://github.com/sphinx-doc/sphinx/pull/9166
> >
> > So, we need to double-check if are there any changes before and after
> > such version at the places container is used - or change the kerneldoc
> > to only emit such tags on PDF depending on the Sphinx version.  
> 
> I've tested things as far back as 2.4.5, where all is well.  I don't
> currently have a machine that is capable of running earlier versions;
> I'll need to conjure one of those up, I guess.
> 
> (Either that or just bite the bullet and move the minimum version
> forward!)

I would just set 2.4.4 as the minimal version. This is already
the minimal version for PDF output anyway:

	my $rec_version = "1.7.9";	# PDF won't build here
	my $min_pdf_version = "2.4.4";	# Min version where pdf builds

and requirements.txt also sets to it. Yet, it would be nice to
change requirements to 2.4.5 as the default pip-installed version.

Regards,
Mauro

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

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab@kernel.org> writes:

> As I didn't test the patches, it sounds worth mentioning that it makes
> sense to check if this won't badly affect epub and/or LaTeX/PDF outputs.
>
> The LaTeX output generator in particular has a problem with long
> lines with fixed-width lines: if the text doesn't fit into one line, it
> either truncates it or makes the text go outside the margins.
>
> If the container affects the PDF outputs, we need to double-check if
> this would break its output.

So as far as I can tell, the PDF output is entirely unaffected.  I have
not read it all, though!  Is there a place in particular that you know
to be problematic where I should look?

Thanks,

jon

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

[Jani Nikula]

On Tue, 04 Oct 2022, Jonathan Corbet <corbet@lwn.net> wrote:
> 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.

Way back I tried to keep the formatting changes minimal to avoid opening
that particular can of worms along with the rest of the Sphinx
transition.

But I do wonder if people find value in repeating e.g. the struct
definitions in the documentation. I'd argue the rendered documentation
is more for an overview, and if you need to know the exact details,
you'll be in the editor typing code and you can look up the actual
definition in source. Having the definition feels maybe a bit excessive.

We also don't use Sphinx C Domain's ".. c:member::" for struct/union
members, or ".. c:enumerator::" for enumeration contants. They provide
arguably nicer rendering out of the box than our stuff.

The Sphinx way to do parameter lists would be field lists i.e. ":param
foo: description". Ditto for return values ":return: description". (Not
saying we should convert the comments, but kernel-doc the script could
emit those.)

Perhaps we'd be better off going towards Sphinx standard usage than
tweaking our own thing?

I'm afraid I don't have the time to work on this. Talk is cheap and all
that. My two cents.

Anyway, here are some examples how this might look like: [1].


BR,
Jani.



[1] https://hawkmoth.readthedocs.io/en/latest/examples.html


>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/sphinx-static/custom.css | 13 +++++++
>  scripts/kernel-doc                     | 52 ++++++++++++++++----------
>  2 files changed, 45 insertions(+), 20 deletions(-)
>
> diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
> index c465251e840a..d8823fbbd27b 100644
> --- a/Documentation/sphinx-static/custom.css
> +++ b/Documentation/sphinx-static/custom.css
> @@ -10,3 +10,16 @@ div.body h3 { font-size: 130%; }
>  
>  /* Tighten up the layout slightly */
>  div.body { padding: 0 15px 0 10px; }
> +
> +/* Don't force the document width */
> +div.document { width: auto; max-width: 60em; }
> +
> +/*
> + * 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..13d42857bce2 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";

-- 
Jani Nikula, Intel Open Source Graphics Center

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

[Mauro Carvalho Chehab]

Em Wed, 05 Oct 2022 19:58:39 +0300
Jani Nikula <jani.nikula@linux.intel.com> escreveu:

> On Tue, 04 Oct 2022, Jonathan Corbet <corbet@lwn.net> wrote:
> > 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.  
> 
> Way back I tried to keep the formatting changes minimal to avoid opening
> that particular can of worms along with the rest of the Sphinx
> transition.
> 
> But I do wonder if people find value in repeating e.g. the struct
> definitions in the documentation. I'd argue the rendered documentation
> is more for an overview, and if you need to know the exact details,
> you'll be in the editor typing code and you can look up the actual
> definition in source. Having the definition feels maybe a bit excessive.

I have split thoughts regards to it. The advantage of having the
struct definition there is to allow checking the type of each argument,
which is useful. It also provide a way to double-check if the parser
is dealing well with the argument, but, on the counter-side, the
type printed by kernel-doc may not be identical to what's inside the
Kernel, on some special cases, as the parse logic for arguments is
complex. The same applies on functions and macros.

> 
> We also don't use Sphinx C Domain's ".. c:member::" for struct/union
> members, 

I'm wondering how much extra build time this would impact ;-)
If the impact is not huge, I'm in favor of using it.

> or ".. c:enumerator::" for enumeration contants. 

This one can be more problematic, as it could break existing
cross-references.

> They provide arguably nicer rendering out of the box than our stuff.

Agreed.

> The Sphinx way to do parameter lists would be field lists i.e. ":param
> foo: description". Ditto for return values ":return: description". (Not
> saying we should convert the comments, but kernel-doc the script could
> emit those.)
> 
> Perhaps we'd be better off going towards Sphinx standard usage than
> tweaking our own thing?
> 
> I'm afraid I don't have the time to work on this. Talk is cheap and all
> that. My two cents.
> 
> Anyway, here are some examples how this might look like: [1].
> 
> 
> BR,
> Jani.
> 
> 
> 
> [1] https://hawkmoth.readthedocs.io/en/latest/examples.html

It reminds that we're currently lacking a  way to describe non-macro
#defines. In special for bit-based defines, it would be nice to have
a good way to document them, without needing to convert defines into 
enums.

Regards,
Mauro

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

[Jani Nikula]

On Thu, 06 Oct 2022, Mauro Carvalho Chehab <mchehab@kernel.org> wrote:
> Em Wed, 05 Oct 2022 19:58:39 +0300
> Jani Nikula <jani.nikula@linux.intel.com> escreveu:
>
>> On Tue, 04 Oct 2022, Jonathan Corbet <corbet@lwn.net> wrote:
>> > 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.  
>> 
>> Way back I tried to keep the formatting changes minimal to avoid opening
>> that particular can of worms along with the rest of the Sphinx
>> transition.
>> 
>> But I do wonder if people find value in repeating e.g. the struct
>> definitions in the documentation. I'd argue the rendered documentation
>> is more for an overview, and if you need to know the exact details,
>> you'll be in the editor typing code and you can look up the actual
>> definition in source. Having the definition feels maybe a bit excessive.
>
> I have split thoughts regards to it. The advantage of having the
> struct definition there is to allow checking the type of each argument,
> which is useful. It also provide a way to double-check if the parser
> is dealing well with the argument, but, on the counter-side, the
> type printed by kernel-doc may not be identical to what's inside the
> Kernel, on some special cases, as the parse logic for arguments is
> complex. The same applies on functions and macros.

Two alternatives to removing it come to mind:

- Generating links to git.kernel.org at right version, file and line.

- A collapsible (and collapsed by default) code box. I think this needs
  html/css hacking, not possible in Sphinx out of the box.

>> 
>> We also don't use Sphinx C Domain's ".. c:member::" for struct/union
>> members, 
>
> I'm wondering how much extra build time this would impact ;-)
> If the impact is not huge, I'm in favor of using it.
>
>> or ".. c:enumerator::" for enumeration contants. 
>
> This one can be more problematic, as it could break existing
> cross-references.

Certainly.

>
>> They provide arguably nicer rendering out of the box than our stuff.
>
> Agreed.
>
>> The Sphinx way to do parameter lists would be field lists i.e. ":param
>> foo: description". Ditto for return values ":return: description". (Not
>> saying we should convert the comments, but kernel-doc the script could
>> emit those.)
>> 
>> Perhaps we'd be better off going towards Sphinx standard usage than
>> tweaking our own thing?
>> 
>> I'm afraid I don't have the time to work on this. Talk is cheap and all
>> that. My two cents.
>> 
>> Anyway, here are some examples how this might look like: [1].
>> 
>> 
>> BR,
>> Jani.
>> 
>> 
>> 
>> [1] https://hawkmoth.readthedocs.io/en/latest/examples.html
>
> It reminds that we're currently lacking a  way to describe non-macro
> #defines. In special for bit-based defines, it would be nice to have
> a good way to document them, without needing to convert defines into 
> enums.

ITYM simple or non-function-like macros. Sphinx supports ".. macro::"
for that nowadays, but don't know since what version. That's what I use
in Hawkmoth, and ".. function::" for macros with args.

BR,
Jani.

>
> Regards,
> Mauro

-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [PATCH RFC 0/5] docs: Improvements to our HTML output

[Mauro Carvalho Chehab]

Hi Jon,

Em Tue,  4 Oct 2022 14:12:17 -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.

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

Re: [PATCH RFC 0/5] docs: Improvements to our HTML output

[Jonathan Corbet]

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

Re: [PATCH RFC 0/5] docs: Improvements to our HTML output

[Mauro Carvalho Chehab]

Em Wed, 05 Oct 2022 09:33:16 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

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

Re: [PATCH RFC 0/5] docs: Improvements to our HTML output

[Jani Nikula]

On Tue, 04 Oct 2022, Jonathan Corbet <corbet@lwn.net> 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

Re: [PATCH RFC 0/5] docs: Improvements to our HTML output

[Jonathan Corbet]

Jani Nikula <jani.nikula@linux.intel.com> 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