From nobody Tue Apr 7 05:03:42 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 D729EC433F5 for ; Tue, 11 Oct 2022 19:01:11 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229989AbiJKTBJ (ORCPT ); Tue, 11 Oct 2022 15:01:09 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54560 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229538AbiJKTA7 (ORCPT ); Tue, 11 Oct 2022 15:00:59 -0400 Received: from ms.lwn.net (ms.lwn.net [IPv6:2600:3c01:e000:3a1::42]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E74B48304D; Tue, 11 Oct 2022 12:00:57 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id 56D987F9; Tue, 11 Oct 2022 19:00:57 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 56D987F9 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1665514857; bh=pTPVZaeeJh0pVq8eQZg8QLde/V+YESX5niUBMm79s9o=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=XUL1z5BFOIV/rptuJr5HafYkGIzefr35U7LAGoQL2iSQKSGDXr290q5QK756yzoug a5LZFj9Wow7Lv+i+rTJK0Z6KK5oRA0gt8e5R5J1LobSoLrr4av7owJoA2gcaF0YNxq 1Udq9LQiVtyIanDVd1teFLd4l21V6Q6QHRyG+wk9OvRASSnxFLwTlKZjcBN1k12SXC ok4PkqA9/Ct8Cad2XqDlewe/iEtY8fJ7mhjR2+7I9lDgTuthC0SC1xacBJtYVCtOcm I7PjgrR1464rBhB4wQnwEvwW6Vi+unzTvKe5o/ViCFYLZfFzf7m2SNUgSamS53QzMQ murVV8hUxVGug== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH v2 1/6] docs: Switch the default HTML theme to alabaster Date: Tue, 11 Oct 2022 13:00:42 -0600 Message-Id: <20221011190047.749145-2-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221011190047.749145-1-corbet@lwn.net> References: <20221011190047.749145-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 Acked-by: Mauro Carvalho Chehab --- 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 Tue Apr 7 05:03:42 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 A306CC433FE for ; Tue, 11 Oct 2022 19:01:18 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230005AbiJKTBP (ORCPT ); Tue, 11 Oct 2022 15:01:15 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54598 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229700AbiJKTBC (ORCPT ); Tue, 11 Oct 2022 15:01:02 -0400 Received: from ms.lwn.net (ms.lwn.net [IPv6:2600:3c01:e000:3a1::42]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 3A388844E1; Tue, 11 Oct 2022 12:00:58 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id B6B9D845; Tue, 11 Oct 2022 19:00:57 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net B6B9D845 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1665514858; bh=RQjiDw6MALWVNaPpx7GNcchSIXCX/ensCVvHPIlQ7jM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=QLjUrv2P4sOQpSCifH8LOLPv1gnfW8VvZRl+pZYD327yMNUvF/gO7ZtphJGq3N9DB 2wnHhz8nWbOSogiNqIMq6atANuPDKcg1/Byc4j8DCWI0ioIQ5KuEF/5yqnomzK21Us cGujxMxou1a7U5JjxkbmnaTHlhHNhu/zTukqOoeCXzbOnp2wbW93e+3ZWqrf/3HX3A chfxoz1XX2uAbCDR6iSE7RpuxOit11oEMzkLYPHsySmqt1YQrG669JidGdDXT6AsEb HyC4vGh4zCtBMsCo8gbwz0c6xBrzr1dU2GxdCptTXV9bfLgSdUgM8yfjKsnD44gYVG U/oH9D7z2B2FA== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH v2 2/6] docs: tweak some Alabaster style parameters Date: Tue, 11 Oct 2022 13:00:43 -0600 Message-Id: <20221011190047.749145-3-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221011190047.749145-1-corbet@lwn.net> References: <20221011190047.749145-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. 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 Acked-by: Mauro Carvalho Chehab --- 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 =3D=3D 'classic': else: html_theme_options =3D { 'description': get_cline_version(), + 'font_size': '10pt', + 'page_width': '65em', + 'sidebar_width': '15em', } =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..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; } --=20 2.37.2 From nobody Tue Apr 7 05:03:42 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 AC8A6C433F5 for ; Tue, 11 Oct 2022 19:01:22 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229659AbiJKTBV (ORCPT ); Tue, 11 Oct 2022 15:01:21 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54614 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229456AbiJKTBD (ORCPT ); Tue, 11 Oct 2022 15:01:03 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C9C0C82D35; Tue, 11 Oct 2022 12:00:58 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id 226DB993; Tue, 11 Oct 2022 19:00:58 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 226DB993 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1665514858; bh=HMKtofhzkC0BbHU/AlRiFnMQhJNC5T93PGks81TP6Ho=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=gZKU2oRQgeOpyosrSMLURM/RecqDGoGEyb42A45zag0mSZRQVWxwvLVAJ13FxIrFz hRrQsinG5uh4xTEG9nEXdI+TPRTGrzUUwkpPItMIZOXCsGfVQIWeTfufbqjGqUuEIj l6vpGqYZXftiuDKAc9ZAuDSG8EqTjYYVN+IzgLvSFQ1abd3ScsNALOpcckwVYeSQhs qYp/6VkioMtSBU13zPthYHz1i+zrWHI95x8QNWJFAQQb/WmgrUGb//7kcphUT8GrAF m5Xtyqy4p2ISQVRj5bbRL35BTVQZOk4kFN4hCP/rlipRggGW1vpHyqohWDLrH0hwvj Xc0hQnkU8GPXQ== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH v2 3/6] docs: update sphinx.rst to reflect the default theme change Date: Tue, 11 Oct 2022 13:00:44 -0600 Message-Id: <20221011190047.749145-4-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221011190047.749145-1-corbet@lwn.net> References: <20221011190047.749145-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 Acked-by: Mauro Carvalho Chehab --- 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 Tue Apr 7 05:03:42 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 7E0D5C433F5 for ; Tue, 11 Oct 2022 19:01:29 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230034AbiJKTB0 (ORCPT ); Tue, 11 Oct 2022 15:01:26 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54630 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229837AbiJKTBE (ORCPT ); Tue, 11 Oct 2022 15:01:04 -0400 Received: from ms.lwn.net (ms.lwn.net [IPv6:2600:3c01:e000:3a1::42]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C99638263D; Tue, 11 Oct 2022 12:00:58 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id 85796197F; Tue, 11 Oct 2022 19:00:58 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 85796197F DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1665514858; bh=hJ7ssfMtbgBA0SjAT4Inkea7XgTAme5JsmDhLulk9CQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=izd2KXK0byOUWqK4osKVPxpVo1gFsR3ysSOqkhz7JmcfjcbbheW1WC3zwNvA3vfQ+ YnnMG2uBU1E5/W5CO5sghZslhWVrZP9jhpKoQ8bQDzOHjYr5vpNLKILrQvNNK3JJbU 4bWwzVa57JN6LhRCbQZ68hH6whcKkp2XKfdAFEmb9ryRDCB6AGYhGfuWylAu8szsew LJwPUyWgKCowqB3oGkdF8ZtczeRJVcY2d+E3145VA+oavC1LlwkoKDjBGedbgosa+h 1lE87foFiyZ+b4c7zI809K2LADx4s0ZQeviJklJy//MOV0vmqVwiCP+sQIBWyQ4lTv eGDpOjAeICpcg== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH v2 4/6] docs: sphinx-pre-install: don't require the RTD theme Date: Tue, 11 Oct 2022 13:00:45 -0600 Message-Id: <20221011190047.749145-5-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221011190047.749145-1-corbet@lwn.net> References: <20221011190047.749145-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 Acked-by: Mauro Carvalho Chehab --- 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 Tue Apr 7 05:03:42 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 5B510C433F5 for ; Tue, 11 Oct 2022 19:01:38 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229935AbiJKTBc (ORCPT ); Tue, 11 Oct 2022 15:01:32 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54632 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229851AbiJKTBE (ORCPT ); Tue, 11 Oct 2022 15:01:04 -0400 Received: from ms.lwn.net (ms.lwn.net [IPv6:2600:3c01:e000:3a1::42]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id CA58385598; Tue, 11 Oct 2022 12:00:59 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id E90CEFFC; Tue, 11 Oct 2022 19:00:58 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net E90CEFFC DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1665514859; bh=j93w6zPd4M0CJXw8HG0zMVIa14pkPXiUGG6IK/auGYs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=JwdZYQ2W6nBVuLnnr5df9xjgNWmp97A32BWxzAF9Xz+zcQdi/XuK3vuxEOmQT9Yns wyMcf5o+Cm1cKa4ASuYsayZ/16iSA6fTP0Fsv6liQ3g2lku2okJtIiuCq6hwqo+B/y NyrpB+OMJfY1O8PmndGrzdL3dz8gpj1sbtsHaekmL22C0B0HLdSgz2RYz6DfN6b+yJ qyEMxJH/ZwYBrLfWVC3nOaQtjnH046k5X1F2UjTPhOT4sTy0ZbW4uuBW0j2PTKuoc0 /CpM8iPTc+et/COjq3oD2W3RIKWkbL9RqB9a3TV+J3K5FFa7OrM590yJLHcLjAtLf0 tdm6NgbFB6rUw== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH v2 5/6] docs: improve the HTML formatting of kerneldoc comments Date: Tue, 11 Oct 2022 13:00:46 -0600 Message-Id: <20221011190047.749145-6-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221011190047.749145-1-corbet@lwn.net> References: <20221011190047.749145-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 Acked-by: Mauro Carvalho Chehab --- 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%; } =20 /* 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;=20 + 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: #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..85ea80fb5154 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 he= lp + # 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 From nobody Tue Apr 7 05:03:42 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 98152C433F5 for ; Tue, 11 Oct 2022 19:01:47 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230099AbiJKTBo (ORCPT ); Tue, 11 Oct 2022 15:01:44 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54634 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229832AbiJKTBE (ORCPT ); Tue, 11 Oct 2022 15:01:04 -0400 Received: from ms.lwn.net (ms.lwn.net [IPv6:2600:3c01:e000:3a1::42]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 2FC1F85A9E; Tue, 11 Oct 2022 12:00:59 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id 53BD61C33; Tue, 11 Oct 2022 19:00:59 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 53BD61C33 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1665514859; bh=eeNjJSKPOPDhILZEGRPPWUGf0HrxtRLOdknTiYDbf7k=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FE+SaK+SskDHqsXJemfqmCsPhSonSqHZV4VN8tcHoexnybb844HRCUknkdrSuMAsR wEY0DmHDphPTjgag1vzzKettIxdbw7F5Fr1L+sc87WQhF8R3m8QI6r0x5Za8oX1ss1 mKF4yOAS5TfJzDOyDjI20d9HQZdsh0RZk+J9b60J4oQ4lo4+TFh3awsxY97AHrDv20 vFl31zug0pAOclmrYrysY+ks37BIY/rV+OM97LEf7buRo1PtRJeIvzcikzqyBdDUgE YebppQwwXXIDlwHg5xMFgSaVyrAcvNGW2K32CfPNnc77B3FtZ1DJAxroamJ0NM3Rmk bqi2wN72Jdviw== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH v2 6/6] docs: decruft Documentation/conf.py Date: Tue, 11 Oct 2022 13:00:47 -0600 Message-Id: <20221011190047.749145-7-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221011190047.749145-1-corbet@lwn.net> References: <20221011190047.749145-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" 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 Signed-off-by: Jonathan Corbet Acked-by: Mauro Carvalho Chehab --- 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 =3D=3D 'sphinx_rtd_theme' or html_theme = =3D=3D 'sphinx_rtd_dark_mode': html_css_files.append('theme_rtd_colors.css') =20 except ImportError: - html_theme =3D 'classic' + html_theme =3D 'alabaster' =20 if "DOCS_CSS" in os.environ: css =3D os.environ["DOCS_CSS"].split(" ") @@ -313,36 +313,7 @@ if major <=3D 1 and minor < 8: for l in html_css_files: html_context['css_files'].append('_static/' + l) =20 -if html_theme =3D=3D 'classic': - html_theme_options =3D { - '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 =3D=3D 'alabaster': html_theme_options =3D { 'description': get_cline_version(), 'font_size': '10pt', @@ -352,44 +323,11 @@ else: =20 sys.stderr.write("Using %s theme\n" % html_theme) =20 -# Theme options are theme-specific and customize the look and feel of a th= eme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options =3D {} - -# Add any paths that contain custom themes here, relative to this director= y. -#html_theme_path =3D [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title =3D None - -# A shorter title for the navigation bar. Default is the same as html_tit= le. -#html_short_title =3D None - -# The name of an image file (relative to this directory) to place at the t= op -# of the sidebar. -#html_logo =3D 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 32x= 32 -# pixels large. -#html_favicon =3D None - # Add any paths that contain custom static files (such as style sheets) he= re, # relative to this directory. They are copied after the builtin static fil= es, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path =3D ['sphinx-static'] =20 -# 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 =3D [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bott= om, -# using the given strftime format. -#html_last_updated_fmt =3D '%b %d, %Y' - # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. html_use_smartypants =3D False @@ -398,50 +336,6 @@ html_use_smartypants =3D False # Note that the RTD theme ignores this 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. -#html_additional_pages =3D {} - -# If false, no module index is generated. -#html_domain_indices =3D True - -# If false, no index is generated. -#html_use_index =3D True - -# If true, the index is split into individual pages for each letter. -#html_split_index =3D False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink =3D True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is = True. -#html_show_sphinx =3D True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is Tru= e. -#html_show_copyright =3D True - -# If true, an OpenSearch description file will be output, and all pages wi= ll -# contain a tag referring to it. The value of this option must be = the -# base URL from which the finished HTML is served. -#html_use_opensearch =3D '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix =3D 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 =3D 'en' - -# A dictionary with options for the search language support, empty by defa= ult. -# Now only 'ja' uses this config value -#html_search_options =3D {'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 =3D 'scorer.js' - # Output file base name for HTML help builder. htmlhelp_basename =3D 'TheLinuxKerneldoc' =20 @@ -583,19 +477,6 @@ texinfo_documents =3D [ 'Miscellaneous'), ] =20 -# Documents to append as an appendix to all manuals. -#texinfo_appendices =3D [] - -# If false, no module index is generated. -#texinfo_domain_indices =3D True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls =3D 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu =3D False - - # -- Options for Epub output ---------------------------------------------- =20 # Bibliographic Dublin Core info. @@ -604,67 +485,9 @@ epub_author =3D author epub_publisher =3D author epub_copyright =3D copyright =20 -# The basename for the epub file. It defaults to the project name. -#epub_basename =3D 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 =3D 'epub' - -# The language of the text. It defaults to the language option -# or 'en' if the language is not set. -#epub_language =3D '' - -# The scheme of the identifier. Typical schemes are ISBN or URL. -#epub_scheme =3D '' - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -#epub_identifier =3D '' - -# A unique identification for the text. -#epub_uid =3D '' - -# A tuple containing the cover image and cover page html template filename= s. -#epub_cover =3D () - -# A sequence of (type, uri, title) tuples for the guide element of content= .opf. -#epub_guide =3D () - -# 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 =3D [] - -# 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 =3D [] - # A list of files that should not be packed into the epub file. epub_exclude_files =3D ['search.html'] =20 -# The depth of the table of contents in toc.ncx. -#epub_tocdepth =3D 3 - -# Allow duplicate toc entries. -#epub_tocdup =3D True - -# Choose between 'default' and 'includehidden'. -#epub_tocscope =3D 'default' - -# Fix unsupported image types using the Pillow. -#epub_fix_images =3D False - -# Scale large images. -#epub_max_image_width =3D 0 - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#epub_show_urls =3D 'inline' - -# If false, no index is generated. -#epub_use_index =3D True - #=3D=3D=3D=3D=3D=3D=3D # rst2pdf # --=20 2.37.2