From nobody Mon Apr 6 18:07:55 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 307C4C4332F for ; Thu, 13 Oct 2022 17:29:35 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229550AbiJMR3c (ORCPT ); Thu, 13 Oct 2022 13:29:32 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:48178 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229470AbiJMR31 (ORCPT ); Thu, 13 Oct 2022 13:29:27 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D7292C34E3; Thu, 13 Oct 2022 10:29:26 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73:8b7:7001:c8aa:b65f]) by ms.lwn.net (Postfix) with ESMTPA id 78173845; Thu, 13 Oct 2022 17:29:26 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 78173845 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1665682166; bh=GPZZbukyBGUR5a86BzVdFY5tNFwcRKGUe05DCy1zk04=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=iGsJwX2B2cftuZzw4pvOPmwBZ3A6w9DXtitUXVKpb9s/Qfj0kXgL8JzdDaGQ3iD2u W/KhRS6FQzv2ff2tkeZoYhT1MsLOJVEUYv/h3zChui0WEe1felJ7R4o+FMde4vDurV XLdNCZLqfC6v9MUg1YkXF/vHnQOE58AmsBK+wR9adKPjHcZ6D6CV3Cgn1BviuOeOaG gxrbqpD3aWinED2Edjp+xW/UipN+Gmd78L0gh9erHbaPlgxi91xRwahxXbmU0EOSu6 q1R2ita4AvqnubQmmUnb+eFSBEbZK3dISPacuFbI+GLkItM1xDFvgcvSvQOVQjAisQ caDFkNchGG60g== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org Subject: [PATCH v3 1/6] docs: Switch the default HTML theme to alabaster Date: Thu, 13 Oct 2022 11:29:13 -0600 Message-Id: <20221013172918.846856-2-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221013172918.846856-1-corbet@lwn.net> References: <20221013172918.846856-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. Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index b50c85083149..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 @@ -370,8 +392,8 @@ html_static_path =3D ['sphinx-static'] 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']} +# 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. --=20 2.37.2 From nobody Mon Apr 6 18:07:55 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 99F50C433FE for ; Thu, 13 Oct 2022 17:29:39 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229883AbiJMR3f (ORCPT ); Thu, 13 Oct 2022 13:29:35 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:48180 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229618AbiJMR31 (ORCPT ); Thu, 13 Oct 2022 13:29:27 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 3E805C3541; Thu, 13 Oct 2022 10:29:27 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73:8b7:7001:c8aa:b65f]) by ms.lwn.net (Postfix) with ESMTPA id CAB5A7DE; Thu, 13 Oct 2022 17:29:26 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net CAB5A7DE DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1665682167; bh=sf2YcBaC8BulfV1gLC66FnN/Vr7mvopLL1hXvmP/Wiw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FqTyH8aSX2v/yn/lGIScRydi6QzAMazqsuDtDXFp4Tlpbs9GQggtulozm8WAnRhpR XVHtJwd1uAP6kBb1CGSe91z/O8NRNhy/4jbeyKTK2+8oF6v8WVmwIxqxnC2+CZdVQR E+UZcJyCDPWbj+VcnjnFlS0bWVWNY7wyafOXuA9B3CBpkTdehkbbvC8td7lSRf6Dgi doW6lPY/TXPwq57q9mw3ll4k8eP/wz+4Z7T0jPEeq9IVD8PJBF86aAQ6ToGozzlB24 3OiTsbGTpMH4KRAGzD8lI0zYBpy0vlbGFBp7sAGOGqBegzAhdgyktKAoPNQEwfwa3q /YvJYPTHWkNdA== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org Subject: [PATCH v3 2/6] docs: tweak some Alabaster style parameters Date: Thu, 13 Oct 2022 11:29:14 -0600 Message-Id: <20221013172918.846856-3-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221013172918.846856-1-corbet@lwn.net> References: <20221013172918.846856-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. Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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 Mon Apr 6 18:07:55 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 04E4AC4332F for ; Thu, 13 Oct 2022 17:29:45 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229888AbiJMR3n (ORCPT ); Thu, 13 Oct 2022 13:29:43 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:48194 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229826AbiJMR32 (ORCPT ); Thu, 13 Oct 2022 13:29:28 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 93BECC4596; Thu, 13 Oct 2022 10:29:27 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73:8b7:7001:c8aa:b65f]) by ms.lwn.net (Postfix) with ESMTPA id 39824FFC; Thu, 13 Oct 2022 17:29:27 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 39824FFC DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1665682167; bh=yEUeV9l6CZglnt5o/00jB7iEk3jA2YvcWBl1vs8MpVQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=kQ/76cfqeiWt+/ntl+wRPAg76DOboVoSmkyfaVY10hUMrwYTj4zz6YzH7pc1f1G79 6mxKHNb9ZnWKg8RlniJqOkNonY2Knvf65DYz7mFa8Wgw+XKOUO0q6+T/e7juPdtr3h OgI/ezspfV4xdzlgGI3BnNBCWCYhqA1ff+EQRvWYyJD/lBOL6vxm4Tah57qlgI0RLX IyRpSm+8xzlAv9sxEePE2/9YzB/tRQqopR6WDA9rV0LOM2YwW2Qwvb2kfyAFtZsKhY 3qOe/zVIJZBkFA4fQSFmZQyAdPrXZsy7CLPZU3kG+32gXAQXFhwVJIweznzryQd7Yw ZkDvuZrK/VcTw== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org Subject: [PATCH v3 3/6] docs: update sphinx.rst to reflect the default theme change Date: Thu, 13 Oct 2022 11:29:15 -0600 Message-Id: <20221013172918.846856-4-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221013172918.846856-1-corbet@lwn.net> References: <20221013172918.846856-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. Acked-by: Mauro Carvalho Chehab 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 c708cec889af..23edb427e76f 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -147,11 +147,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 @@ -160,12 +158,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:55 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 9FD4BC433FE for ; Thu, 13 Oct 2022 17:29:49 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229886AbiJMR3s (ORCPT ); Thu, 13 Oct 2022 13:29:48 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:48206 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229833AbiJMR32 (ORCPT ); Thu, 13 Oct 2022 13:29:28 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id F35C5C34E3; Thu, 13 Oct 2022 10:29:27 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73:8b7:7001:c8aa:b65f]) by ms.lwn.net (Postfix) with ESMTPA id 9186D7F9; Thu, 13 Oct 2022 17:29:27 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 9186D7F9 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1665682167; bh=w3wkfghYAXmRJrVxbzZZnrDjz+QM31pXF6acX37HbWw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=D3GqwBumdV9U5+dZCyn903icHDcZ0uZ7BAbUH5iFPTIHMBLomaKDd69BNFNW7PfGG KEoM+skcQbCegEuK9EwC9MS38pqVyAzTaDZHPogH4+svnQa+gqCt1iAWdXT7DCmrdg Vsz52LzlkcBtb+2noB22zVdhcMKgBEzHHFJNcMieCXYq51EZMgkqcPra4txdQAVYJm IXk+y3mBY1wp0OpPUALKP7IS+53CFl6TydYVrQYgawRqtq77ews1PeSS9Ygvf2rvPL TCLoVGs3uL+l0UNXW04tNjUsUbqOYwkUoRfzQJsVs+kECN/rHigQcwUNjgYjK51Xa7 ZDNXCfqjGT8rw== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org Subject: [PATCH v3 4/6] docs: sphinx-pre-install: don't require the RTD theme Date: Thu, 13 Oct 2022 11:29:16 -0600 Message-Id: <20221013172918.846856-5-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221013172918.846856-1-corbet@lwn.net> References: <20221013172918.846856-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. Acked-by: Mauro Carvalho Chehab 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:55 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 AF0D2C4332F for ; Thu, 13 Oct 2022 17:29:56 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229931AbiJMR3x (ORCPT ); Thu, 13 Oct 2022 13:29:53 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:48212 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229846AbiJMR33 (ORCPT ); Thu, 13 Oct 2022 13:29:29 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 611CDC3541; Thu, 13 Oct 2022 10:29:28 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73:8b7:7001:c8aa:b65f]) by ms.lwn.net (Postfix) with ESMTPA id E49D9845; Thu, 13 Oct 2022 17:29:27 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net E49D9845 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1665682168; bh=0opHrZqvXrL6VtcOxiAU4dw/b0sguVWD5kn6y9m/afo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=CzbjjyF5THDuiifk7pwCcR2BT3lwHJ1v5ySNvbHfr+iosLF/ruylselyA+DC2cr7k weO48FqSQpscOjHUOaMT0rande9wdUNRhRwmwrfsuyNC61y2XEgDygTxApMMj73Xv3 YTx5SpYKE1hI0hkKu6n31+T8rKqr0JJ0uLHVelp+xg7qFM07Sc3WnKvUHbWf7VK38d KXVvscZ1f3llbQC9dVR6YS+LrcL7+bVd6Xmm9HmocARTEiEIOriAgKhD2GYGrddIJ/ DdcHJCEcCo0eizwMAXzE0CpwT/e7OBGYCcxU5bvrZZ4j4pFXPVhxBPx7wqkEAvFw1K 6PVo4JdcFzIXQ== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org Subject: [PATCH v3 5/6] docs: improve the HTML formatting of kerneldoc comments Date: Thu, 13 Oct 2022 11:29:17 -0600 Message-Id: <20221013172918.846856-6-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221013172918.846856-1-corbet@lwn.net> References: <20221013172918.846856-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. Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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 Mon Apr 6 18:07:55 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 52B72C4332F for ; Thu, 13 Oct 2022 17:29:59 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229496AbiJMR35 (ORCPT ); Thu, 13 Oct 2022 13:29:57 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:48218 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229861AbiJMR3a (ORCPT ); Thu, 13 Oct 2022 13:29:30 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C0E61D038E; Thu, 13 Oct 2022 10:29:28 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73:8b7:7001:c8aa:b65f]) by ms.lwn.net (Postfix) with ESMTPA id 44F0C7DE; Thu, 13 Oct 2022 17:29:28 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 44F0C7DE DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1665682168; bh=keh3BAATlkR8yDL2srU6MNeKVExwzXPbSFhQxtmEIdk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=s332vN68n3jqb2xYS+ZyYgEsAFrNsqsWuUvhcbLuNPL0CzQXC+PVGOSKII3104BSk l1SzFbQdQGXojU0xubGNluP7x9pCPqnCpf9x2Jf2wuSs9ucB951+ByUhA6n65n6Yge bZJYhrg7rgIKOPue9b882fj8UBGLN1Ll52ZEXq+2WFy1KQgJ6JrWWsJ1vBwf6ByQYU aB4HswMJiJfBXIG6ipVKRzmEEgR5lsQxC0mrOtbFX4UUrs6Tk/HOi3BxXLN2Bs/ad3 3yBSA5XOvk4gRhiKgA5ZXHnA/YJobyYqpmQWa4/krZ4VRu8ULQJNuJsJtTR+Yyc22B 1InmJOhTu3B5w== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org Subject: [PATCH v3 6/6] docs: decruft Documentation/conf.py Date: Thu, 13 Oct 2022 11:29:18 -0600 Message-Id: <20221013172918.846856-7-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221013172918.846856-1-corbet@lwn.net> References: <20221013172918.846856-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 Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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