From nobody Mon Apr 6 18:07:36 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 90E08C433F5 for ; Tue, 4 Oct 2022 20:12:44 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229764AbiJDUMl (ORCPT ); Tue, 4 Oct 2022 16:12:41 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49374 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229603AbiJDUMh (ORCPT ); Tue, 4 Oct 2022 16:12:37 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 5119526126; Tue, 4 Oct 2022 13:12:36 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id 873884B0; Tue, 4 Oct 2022 20:12:35 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 873884B0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1664914355; bh=pTPVZaeeJh0pVq8eQZg8QLde/V+YESX5niUBMm79s9o=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ZuBL3W96SMr+tG6HClnOWvrBUJrR0VDnq8Su03jY/0TbURTi2/7qW3i01/tCeX/ly uxY3WHJzqr23Z85MeXaUIJC9fbV3d4Yx0QquK5ezQX23RxmDhuIYKbUQDEG+NMNgUJ grTjXsBMTe0mK1VG184z5ipcsMGZQ68vV0hWSS4aRsIQgF+5706U0tx+gyxkdhP8xy GOotBOvAhTldlsBSl/6usiSyMFQylKYINYmDg1awwa4ILn1J7Vn4UVjEMKhRJgvtxC /fBpogGscw/fAadq6tFp31RxowRp4kIya1BXF/qODYtJmrbxMzUvWPoxfmQ/2nC2ux xCucCI+wjwE6A== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH 1/5] docs: Switch the default HTML theme to alabaster Date: Tue, 4 Oct 2022 14:12:18 -0600 Message-Id: <20221004201222.281845-2-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221004201222.281845-1-corbet@lwn.net> References: <20221004201222.281845-1-corbet@lwn.net> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" 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 --- 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 =3D release =3D "unknown version" =20 +# +# 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 t= he +# command-line options and find it for ourselves. +# +def get_cline_version(): + c_version =3D c_release =3D '' + for arg in sys.argv: + if arg.startswith('version=3D'): + c_version =3D arg[8:] + elif arg.startswith('release=3D'): + c_release =3D 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 =3D 'none' # a list of builtin themes. =20 # Default theme -html_theme =3D 'sphinx_rtd_theme' +html_theme =3D 'alabaster' html_css_files =3D [] =20 if "DOCS_THEME" in os.environ: @@ -324,6 +342,10 @@ if html_theme =3D=3D 'classic': 'bodyfont': "serif", 'headfont': "sans-serif", } +else: + html_theme_options =3D { + 'description': get_cline_version(), + } =20 sys.stderr.write("Using %s theme\n" % html_theme) =20 @@ -371,7 +393,7 @@ html_use_smartypants =3D False =20 # Custom sidebar templates, maps document names to template names. # Note that the RTD theme ignores this -html_sidebars =3D { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.= html']} +html_sidebars =3D { '**': ["about.html", 'searchbox.html', 'localtoc.html'= , 'sourcelink.html']} =20 # Additional templates that should be rendered to pages, maps page names to # template names. --=20 2.37.2 From nobody Mon Apr 6 18:07:36 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id B23CDC433FE for ; Tue, 4 Oct 2022 20:12:48 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229843AbiJDUMr (ORCPT ); Tue, 4 Oct 2022 16:12:47 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49380 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229605AbiJDUMh (ORCPT ); Tue, 4 Oct 2022 16:12:37 -0400 Received: from ms.lwn.net (ms.lwn.net [IPv6:2600:3c01:e000:3a1::42]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 91B60222A9; Tue, 4 Oct 2022 13:12:36 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id EA911221; Tue, 4 Oct 2022 20:12:35 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net EA911221 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1664914356; bh=aPqqsdVIL1nw4hjRuQ5Hp50KWG5DPegY2KATgxVsOfk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=QIp72KlxY8nvdrCjzlqAYUjLBaIdLqA+vVQYFomi3NdGgIP2Fu6u/Kz5iybQCgMqe +m20jUUFfHCZKbEHrJJ7kuetP8IwngSmF+BILKf3uZtq6Fv0naPhCrvUVgQyFsg6oT ka414QfhzBc54PeJsZCv01AoVxMq7ggi5ku7c8R7pYedW8ygrhyUvwCyPwXxuJzH2k GId2LMx3NlM65CtwVz27W5u+WFElqewbesl5iwEnBWyL633cEwRhz6KW6NwZgIGNQ4 hr84dtt5uCbRBTERMMZGkBJQilpQV1egdJ0/OCg6bGHR5pkYEVY67H791+4N+X0Pid e0dPwXm4hCriQ== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH 2/5] docs: tweak some Alabaster style parameters Date: Tue, 4 Oct 2022 14:12:19 -0600 Message-Id: <20221004201222.281845-3-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221004201222.281845-1-corbet@lwn.net> References: <20221004201222.281845-1-corbet@lwn.net> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" 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 --- 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 =3D=3D 'classic': else: html_theme_options =3D { 'description': get_cline_version(), + 'font_size': '14px', } =20 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; } --=20 2.37.2 From nobody Mon Apr 6 18:07:36 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 88844C433FE for ; Tue, 4 Oct 2022 20:12:57 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229908AbiJDUMz (ORCPT ); Tue, 4 Oct 2022 16:12:55 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49382 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229643AbiJDUMh (ORCPT ); Tue, 4 Oct 2022 16:12:37 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D823E25EB6; Tue, 4 Oct 2022 13:12:36 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id 63886385; Tue, 4 Oct 2022 20:12:36 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 63886385 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1664914356; bh=HMKtofhzkC0BbHU/AlRiFnMQhJNC5T93PGks81TP6Ho=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=B0kXIj2yzH2+v28tH5gVYRUd/Sv+6Ui0NsS1sljjsm63BD8uTBNcSz8gBDlRk/Cnb bEvdmdUsuvikFO+WEl1hvunxECwT/DJUmkDlOY0qS4gQj9ZDQXWogZWKADSKwd4WaL aiGzKUbupO5l0T1/nQLSkXZTkpka+COuyp2527hcgIZKRq9++e9y3+zYRp180i+k8t TiY7FOs1YF+SlwRFAbaAaLIghZT5+9LU6qqmy/0Xwt0SxahDH446tz2kooNGS1Pkdh 3N3neTzpv/tgJTCkxLD4NACY9sOX60SirXNMhF/g7qzXYpTqcF0elccgCCrY/3UvYv vi4m+oqH5G0Ng== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH 3/5] docs: update sphinx.rst to reflect the default theme change Date: Tue, 4 Oct 2022 14:12:20 -0600 Message-Id: <20221004201222.281845-4-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221004201222.281845-1-corbet@lwn.net> References: <20221004201222.281845-1-corbet@lwn.net> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" We don't default to Read The Docs anymore; update the docs to match. Signed-off-by: Jonathan Corbet --- 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/s= phinx.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``. =20 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 ne= ed -``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. =20 To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make variable. For example, use ``make SPHINXOPTS=3D-v htmldocs`` to get more v= erbose @@ -143,12 +141,8 @@ output. It is also possible to pass an extra DOCS_CSS overlay file, in order to cu= stomize the html layout, by using the ``DOCS_CSS`` make variable. =20 -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 variab= le. =20 There is another make variable ``SPHINXDIRS``, which is useful when test --=20 2.37.2 From nobody Mon Apr 6 18:07:36 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id B08BAC433F5 for ; Tue, 4 Oct 2022 20:12:53 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229870AbiJDUMv (ORCPT ); Tue, 4 Oct 2022 16:12:51 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49392 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229660AbiJDUMi (ORCPT ); Tue, 4 Oct 2022 16:12:38 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 61A2B264BA; Tue, 4 Oct 2022 13:12:37 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id C60B0844; Tue, 4 Oct 2022 20:12:36 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net C60B0844 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1664914357; bh=hJ7ssfMtbgBA0SjAT4Inkea7XgTAme5JsmDhLulk9CQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=kPwPL9q7UNvjRJcURzQx//j/zs5+4QFghxahfteCf+/DO9acKBIJRyYZAeg2Emw8z /pusteuIF/77AtH0mR680+Eb6TAh/rJOI5bNKKf7eYtJPcjOLyAMNJbDyQKuKWLQY+ IJdIhGneMGDFVe2sJb5zL9VlksGtZj4BuDFYTAFJ4RHW3xTxyB/TjLEP/hKr4wqxp7 Q/6wbRTlS6HmP+D+H2injwHB0MnHvHNpEFwPeBPHcPCQ2kBsPRobv3nQoP1GyOHCEw +CuD46cvwcI65CMtFgtllokN+0YjZfYqB75rMcKwNwPwFzHFw5YEa962DQTH7nlWBK mj3N9eDyDswcA== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH 4/5] docs: sphinx-pre-install: don't require the RTD theme Date: Tue, 4 Oct 2022 14:12:21 -0600 Message-Id: <20221004201222.281845-5-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221004201222.281845-1-corbet@lwn.net> References: <20221004201222.281845-1-corbet@lwn.net> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" We don't default to the RTD theme anymore, so sphinx-pre-install need not insist on installing it. Signed-off-by: Jonathan Corbet --- 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/r= equirements.txt index 2c573541ab71..335b53df35e2 100644 --- a/Documentation/sphinx/requirements.txt +++ b/Documentation/sphinx/requirements.txt @@ -1,4 +1,3 @@ # jinja2>=3D3.1 is not compatible with Sphinx<4.0 jinja2<3.1 -sphinx_rtd_theme Sphinx=3D=3D2.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 =3D ( "python-sphinx" =3D> "python3-sphinx", - "sphinx_rtd_theme" =3D> "python3-sphinx-rtd-theme", "ensurepip" =3D> "python3-venv", "virtualenv" =3D> "virtualenv", "dot" =3D> "graphviz", @@ -397,7 +396,6 @@ sub give_redhat_hints() { my %map =3D ( "python-sphinx" =3D> "python3-sphinx", - "sphinx_rtd_theme" =3D> "python3-sphinx_rtd_theme", "virtualenv" =3D> "python3-virtualenv", "dot" =3D> "graphviz", "convert" =3D> "ImageMagick", @@ -475,7 +473,6 @@ sub give_opensuse_hints() { my %map =3D ( "python-sphinx" =3D> "python3-sphinx", - "sphinx_rtd_theme" =3D> "python3-sphinx_rtd_theme", "virtualenv" =3D> "python3-virtualenv", "dot" =3D> "graphviz", "convert" =3D> "ImageMagick", @@ -523,7 +520,6 @@ sub give_mageia_hints() { my %map =3D ( "python-sphinx" =3D> "python3-sphinx", - "sphinx_rtd_theme" =3D> "python3-sphinx_rtd_theme", "virtualenv" =3D> "python3-virtualenv", "dot" =3D> "graphviz", "convert" =3D> "ImageMagick", @@ -567,7 +563,6 @@ sub give_mageia_hints() sub give_arch_linux_hints() { my %map =3D ( - "sphinx_rtd_theme" =3D> "python-sphinx_rtd_theme", "virtualenv" =3D> "python-virtualenv", "dot" =3D> "graphviz", "convert" =3D> "imagemagick", @@ -598,7 +593,6 @@ sub give_arch_linux_hints() sub give_gentoo_hints() { my %map =3D ( - "sphinx_rtd_theme" =3D> "dev-python/sphinx_rtd_theme", "virtualenv" =3D> "dev-python/virtualenv", "dot" =3D> "media-gfx/graphviz", "convert" =3D> "media-gfx/imagemagick", @@ -895,7 +889,6 @@ sub recommend_sphinx_version($) $verbose_warn_install =3D 0; =20 add_package("python-sphinx", 0); - check_python_module("sphinx_rtd_theme", 1); =20 check_distros(); =20 @@ -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); =20 --=20 2.37.2 From nobody Mon Apr 6 18:07:36 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 32FD0C433FE for ; Tue, 4 Oct 2022 20:13:00 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229891AbiJDUM6 (ORCPT ); Tue, 4 Oct 2022 16:12:58 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49394 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229668AbiJDUMi (ORCPT ); Tue, 4 Oct 2022 16:12:38 -0400 Received: from ms.lwn.net (ms.lwn.net [IPv6:2600:3c01:e000:3a1::42]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 9EE02222A9; Tue, 4 Oct 2022 13:12:37 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id 384BF7DC; Tue, 4 Oct 2022 20:12:37 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 384BF7DC DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1664914357; bh=SFg4DeLOFXhMPlmb11hADxqed3o6ZbUJFfnUFY8QYcw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=K0+Txb0N/fxdI/+iyKeVPBDbXqxcS8GWL0XzB8yFClxAVSNWZ2XCqDuRzgjcwgShH iojoJW+AMUtwEm8dniSUcoISmu+zcRBDBUNDr6n3OywJ656JayR08eVLbJLibarqm/ e9LXkLRazlcpLdqgoqRWErCBlqzRgpmHv0WN3Fmr5P6xpmnbBczYJQJ43aATOKLZxp 9bQwIizpZeL9FSh21qjNvazVHsbHiPZAzIOsT3Gw3nQZngKkImTZn933vt9LWWi/GU IPeZTm7dAraYUhbatrrLzcwH/rt1U7uKG6CUFmoAWAoXXfikh3/3t26FWbSx/8I8kr Vhs3AnEC6yZeg== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH 5/5] docs: improve the HTML formatting of kerneldoc comments Date: Tue, 4 Oct 2022 14:12:22 -0600 Message-Id: <20221004201222.281845-6-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221004201222.281845-1-corbet@lwn.net> References: <20221004201222.281845-1-corbet@lwn.net> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" 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 --- 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%; } =20 /* 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: #ecf0= f3; } +/* 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"; } =20 - print "**Parameters**\n\n"; + # + # Put our descriptive text into a container (thus an HTML
to help + # set the function prototypes apart. + # + print ".. container:: kernelindent\n\n"; $lineprefix =3D " "; + print $lineprefix . "**Parameters**\n\n"; foreach $parameter (@{$args{'parameterlist'}}) { my $parameter_name =3D $parameter; $parameter_name =3D~ s/\[.*//; $type =3D $args{'parametertypes'}{$parameter}; =20 if ($type ne "") { - print "``$type``\n"; + print $lineprefix . "``$type``\n"; } else { - print "``$parameter``\n"; + print $lineprefix . "``$parameter``\n"; } =20 print_lineno($parameterdesc_start_lines{$parameter_name}); =20 + $lineprefix =3D " "; 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 =3D " "; print "\n"; } =20 - $lineprefix =3D $oldprefix; output_section_rst(@_); + $lineprefix =3D $oldprefix; } =20 sub output_section_rst(%) { my %args =3D %{$_[0]}; my $section; my $oldprefix =3D $lineprefix; - $lineprefix =3D ""; =20 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 =3D $oldprefix; } =20 sub output_enum_rst(%) { @@ -915,6 +920,7 @@ sub output_enum_rst(%) { my ($parameter); my $oldprefix =3D $lineprefix; my $count; + my $outer; =20 if ($sphinx_major < 3) { my $name =3D "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 =3D " "; + $lineprefix =3D " "; output_highlight_rst($args{'purpose'}); print "\n"; =20 - print "**Constants**\n\n"; - $lineprefix =3D " "; + print ".. container:: kernelindent\n\n"; + $outer =3D $lineprefix . " "; + $lineprefix =3D $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 =3D $oldprefix; output_section_rst(@_); } @@ -982,18 +991,19 @@ sub output_struct_rst(%) { } } print_lineno($declaration_start_line); - $lineprefix =3D " "; + $lineprefix =3D " "; output_highlight_rst($args{'purpose'}); print "\n"; =20 - print "**Definition**\n\n"; - print "::\n\n"; + print ".. container:: kernelindent\n\n"; + print $lineprefix . "**Definition**::\n\n"; my $declaration =3D $args{'definition'}; - $declaration =3D~ s/\t/ /g; - print " " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration= };\n\n"; + $lineprefix =3D $lineprefix . " "; + $declaration =3D~ s/\t/$lineprefix/g; + print $lineprefix . $args{'type'} . " " . $args{'struct'} . " {\n$decl= aration" . $lineprefix . "};\n\n"; =20 - print "**Members**\n\n"; $lineprefix =3D " "; + print $lineprefix . "**Members**\n\n"; foreach $parameter (@{$args{'parameterlist'}}) { ($parameter =3D~ /^#/) && next; =20 @@ -1003,8 +1013,10 @@ sub output_struct_rst(%) { ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; $type =3D $args{'parametertypes'}{$parameter}; print_lineno($parameterdesc_start_lines{$parameter_name}); - print "``" . $parameter . "``\n"; + print $lineprefix . "``" . $parameter . "``\n"; + $lineprefix =3D " "; output_highlight_rst($args{'parameterdescs'}{$parameter_name}); + $lineprefix =3D " "; print "\n"; } print "\n"; --=20 2.37.2