From nobody Mon Apr 6 21:35:25 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 4AE2EECAAD2 for ; Thu, 1 Sep 2022 23:16:58 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234977AbiIAXQ4 (ORCPT ); Thu, 1 Sep 2022 19:16:56 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41770 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234856AbiIAXQs (ORCPT ); Thu, 1 Sep 2022 19:16:48 -0400 Received: from ms.lwn.net (ms.lwn.net [IPv6:2600:3c01:e000:3a1::42]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 4080595AE2; Thu, 1 Sep 2022 16:16:48 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id D71F24B0; Thu, 1 Sep 2022 23:16:47 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net D71F24B0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1662074208; bh=zC5DmfnmcyjofvsDiYdnGJiX2/WFvTpVfVyoJDzoBRw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=VPl0qwAXf0jJUJ+kMF14oSlUaaHgYmePfwKdJ6N/JECv25bH/T4ovJHz145s0WxT/ 696jpqbGAgSQPzuNDCSrmx2eWqc/+3672qx65iehKUKRTdPJ9a54sYhbcDhtyfBmin zcjnOInu7OsDz1K4zO79Q5s4a0tRpWy2VBdF9ncZkaJi54RkuAWZNUA547z967B//r GA68IyuCquocxcB+Exob3uP5Vi6CmM2FT34KBjrhKtglsUsX3soruLahC9++vr3IIv E8UT84fh/D0RlkY34NJvGtnTBfraynt0b9XXCXMpOvhMo5e+ZYb5eiInyyZmnBd+ys pG4owU65/plTg== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jonathan Corbet Subject: [PATCH 1/4] docs: promote the title of process/index.html Date: Thu, 1 Sep 2022 17:16:29 -0600 Message-Id: <20220901231632.518583-2-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20220901231632.518583-1-corbet@lwn.net> References: <20220901231632.518583-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" ...otherwise Sphinx won't cooperate when trying to list it explicitly in the top-level index.rst file Signed-off-by: Jonathan Corbet --- Documentation/process/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Documentation/process/index.rst b/Documentation/process/index.= rst index 2ba2a1582bbe..d4b6217472b0 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -5,6 +5,7 @@ =20 .. _process_index: =20 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D Working with the kernel development community =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 --=20 2.37.2 From nobody Mon Apr 6 21:35:25 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 72C8EECAAD2 for ; Thu, 1 Sep 2022 23:17:04 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S235089AbiIAXRB (ORCPT ); Thu, 1 Sep 2022 19:17:01 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41786 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234915AbiIAXQt (ORCPT ); Thu, 1 Sep 2022 19:16:49 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id BD5D095AE2; Thu, 1 Sep 2022 16:16:48 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id 4A7BE77D; Thu, 1 Sep 2022 23:16:48 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 4A7BE77D DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1662074208; bh=5FFDPRQHqb/toPn6VxY6WKFENrWTkLzbve5YcQmY7co=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=HdII4Mjz762XWuLa6PcKYSR15TqDCyFH51D3zCSCTVd2CA4Ew6IDpc4t7KldFnu5P kz2VG+vuzEqdYbmqeAIcPTTrlrGD8jbNa70/dZYVnhMvN/+S7v1/UVay9/omK9nzFI taMfk+nb2wEWu5sIlBfS1CG48uSyEuwOfN/0kx4qHYX+eGE6FO4tzTLbTg9MDXpJu/ SrYhBrXiGUR3Eo3rob2tyR4V2hQDTFTG1/QgCwOWuIIycWblHJgD2H2L0JFoNDHloR tsoftUVW3YyZu/xJP4dZ/VgK+1ZidGczGepykCBp3dvyAiL9tRf3doeRWsPqLh+/JJ b2g6PFMQEW1tw== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jonathan Corbet Subject: [PATCH 2/4] docs: Rewrite the front page Date: Thu, 1 Sep 2022 17:16:30 -0600 Message-Id: <20220901231632.518583-3-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20220901231632.518583-1-corbet@lwn.net> References: <20220901231632.518583-1-corbet@lwn.net> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org The front page is the entry point to the documentation, especially for people who read it online. It's a big mess of everything we could think to toss into it. Rewrite the page with an eye toward simplicity and making it easy for readers to get going toward what they really want to find. This is only a beginning, but it makes our docs more approachable than before. Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 151 ++++++++++++------------------- Documentation/subsystem-apis.rst | 56 ++++++++++++ 2 files changed, 113 insertions(+), 94 deletions(-) create mode 100644 Documentation/subsystem-apis.rst diff --git a/Documentation/index.rst b/Documentation/index.rst index 4737c18c97ff..428cfd8e369b 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -18,14 +18,52 @@ documents into a coherent whole. Please note that impr= ovements to the documentation are welcome; join the linux-doc list at vger.kernel.org if you want to help out. =20 -Licensing documentation ------------------------ +Working with the development community +-------------------------------------- =20 -The following describes the license of the Linux kernel source code -(GPLv2), how to properly mark the license of individual files in the source -tree, as well as links to the full license text. +The essential guides for interacting with the kernel's development +community and getting your work upstream. + +.. toctree:: + :maxdepth: 1 + + process/development-process + process/submitting-patches + Code of conduct + maintainer/index + All development-process docs + + +Internal API manuals +-------------------- + +Manuals for use by developers working to interface with the rest of the +kernel. + +.. toctree:: + :maxdepth: 1 + + core-api/index + driver-api/index + subsystem-apis + Locking in the kernel + +Development tools and processes +------------------------------- + +Various other manuals with useful information for all kernel developers. + +.. toctree:: + :maxdepth: 1 + + process/license-rules + doc-guide/index + dev-tools/index + kernel-hacking/index + trace/index + fault-injection/index + livepatch/index =20 -* :ref:`kernel_licensing` =20 User-oriented documentation --------------------------- @@ -34,21 +72,10 @@ The following manuals are written for *users* of the ke= rnel =E2=80=94 those who are trying to get it to work optimally on a given system. =20 .. toctree:: - :maxdepth: 2 + :maxdepth: 1 =20 admin-guide/index - kbuild/index - -Firmware-related documentation ------------------------------- -The following holds information on the kernel's expectations regarding the -platform firmwares. - -.. toctree:: - :maxdepth: 2 - - firmware-guide/index - devicetree/index + The kernel build system =20 Application-developer documentation ----------------------------------- @@ -57,92 +84,28 @@ The user-space API manual gathers together documents de= scribing aspects of the kernel interface as seen by application developers. =20 .. toctree:: - :maxdepth: 2 + :maxdepth: 1 =20 userspace-api/index =20 =20 -Introduction to kernel development ----------------------------------- - -These manuals contain overall information about how to develop the kernel. -The kernel community is quite large, with thousands of developers -contributing over the course of a year. As with any large community, -knowing how things are done will make the process of getting your changes -merged much easier. +Firmware-related documentation +------------------------------ +The following holds information on the kernel's expectations regarding the +platform firmwares. =20 .. toctree:: - :maxdepth: 2 + :maxdepth: 1 =20 - process/index - dev-tools/index - doc-guide/index - kernel-hacking/index - trace/index - maintainer/index - fault-injection/index - livepatch/index - - -Kernel API documentation ------------------------- - -These books get into the details of how specific kernel subsystems work -from the point of view of a kernel developer. Much of the information here -is taken directly from the kernel source, with supplemental material added -as needed (or at least as we managed to add it =E2=80=94 probably *not* al= l that is -needed). - -.. toctree:: - :maxdepth: 2 + firmware-guide/index + devicetree/index =20 - driver-api/index - core-api/index - locking/index - accounting/index - block/index - cdrom/index - cpu-freq/index - fb/index - fpga/index - hid/index - i2c/index - iio/index - isdn/index - infiniband/index - leds/index - netlabel/index - networking/index - pcmcia/index - power/index - target/index - timers/index - spi/index - w1/index - watchdog/index - virt/index - input/index - hwmon/index - gpu/index - security/index - sound/index - crypto/index - filesystems/index - mm/index - bpf/index - usb/index - PCI/index - scsi/index - misc-devices/index - scheduler/index - mhi/index - peci/index =20 Architecture-agnostic documentation ----------------------------------- =20 .. toctree:: - :maxdepth: 2 + :maxdepth: 1 =20 asm-annotations =20 @@ -150,7 +113,7 @@ Architecture-specific documentation ----------------------------------- =20 .. toctree:: - :maxdepth: 2 + :maxdepth: 1 =20 arch =20 @@ -163,7 +126,7 @@ of the documentation body, or may require some adjustme= nts and/or conversion to ReStructured Text format, or are simply too old. =20 .. toctree:: - :maxdepth: 2 + :maxdepth: 1 =20 tools/index staging/index diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-api= s.rst new file mode 100644 index 000000000000..f5d8bcc023c8 --- /dev/null +++ b/Documentation/subsystem-apis.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Kernel subsystem API documentation +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +These books get into the details of how specific kernel subsystems work +from the point of view of a kernel developer. Much of the information here +is taken directly from the kernel source, with supplemental material added +as needed (or at least as we managed to add it =E2=80=94 probably *not* al= l that is +needed). + +.. toctree:: + :maxdepth: 1 + + driver-api/index + core-api/index + locking/index + accounting/index + block/index + cdrom/index + cpu-freq/index + fb/index + fpga/index + hid/index + i2c/index + iio/index + isdn/index + infiniband/index + leds/index + netlabel/index + networking/index + pcmcia/index + power/index + target/index + timers/index + spi/index + w1/index + watchdog/index + virt/index + input/index + hwmon/index + gpu/index + security/index + sound/index + crypto/index + filesystems/index + mm/index + bpf/index + usb/index + PCI/index + scsi/index + misc-devices/index + scheduler/index + mhi/index + peci/index --=20 2.37.2 From nobody Mon Apr 6 21:35:25 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 39057ECAAD2 for ; Thu, 1 Sep 2022 23:17:11 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233595AbiIAXRK (ORCPT ); Thu, 1 Sep 2022 19:17:10 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41802 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233701AbiIAXQu (ORCPT ); Thu, 1 Sep 2022 19:16:50 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 8A3739AFA9; Thu, 1 Sep 2022 16:16:49 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id ADF5E2B8; Thu, 1 Sep 2022 23:16:48 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net ADF5E2B8 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1662074209; bh=pjEqGsC3o1cCyVpcxwjXhbptLW8M3DxLII6MXHLKxx4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=HttwhfoNd2RBCMXJyH3N5bOHMY8PiWeXU1xreO7WiF/30gPdnyEx/tMdeurqK1kWx URVJCAicwSKYhN2RBXjmNJn7Xll1exANcYBIYJVF80j1nkolfEc9zgFuGs+T7S/Jhy 9xnW25hwAumA4FN7OeK/WtGFyo06HW2O8JdFnpbPeX7bwj31SoMmZRM1Q8NdG5H2zc yCmWGjoVfUUaNjK62cPaWrRueB/IDSOkdr02SdUrHUoDR20GVAxtwAkP2OCKO9ESj6 r0tCQm8pgiigvhk1azYvKCuDnQcchdHUo63veJLaT2E8rY4EHW0gREcFblahCHV1ov T1K6B/dntzGlQ== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jonathan Corbet Subject: [PATCH 3/4] docs: reconfigure the HTML left column Date: Thu, 1 Sep 2022 17:16:31 -0600 Message-Id: <20220901231632.518583-4-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20220901231632.518583-1-corbet@lwn.net> References: <20220901231632.518583-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" Use the html_sidebars directive to get a more useful set of links in the left column. Unfortunately, this is a no-op with the default RTD theme, but others observe it. Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 78dd6d1e7b88..22c9d4df1967 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -370,7 +370,8 @@ html_static_path =3D ['sphinx-static'] html_use_smartypants =3D False =20 # Custom sidebar templates, maps document names to template names. -#html_sidebars =3D {} +# Note that the RTD theme ignores this +html_sidebars =3D { '**': ['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 21:35:25 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 81437ECAAD3 for ; Thu, 1 Sep 2022 23:17:07 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S235110AbiIAXRG (ORCPT ); Thu, 1 Sep 2022 19:17:06 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41804 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232787AbiIAXQu (ORCPT ); Thu, 1 Sep 2022 19:16:50 -0400 Received: from ms.lwn.net (ms.lwn.net [IPv6:2600:3c01:e000:3a1::42]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id B12909AFE7; Thu, 1 Sep 2022 16:16:49 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id 2A95B4B0; Thu, 1 Sep 2022 23:16:49 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 2A95B4B0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1662074209; bh=GP+jI/OmcP1ezTMxKf+XkGnohxp5U+e1AerLNBe5NI8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=crN6744af9TaacEMy3wyiVXPGVCVgjiXUiNoCKjSKTg4cqJolf450MLwxRChu5WIZ C/jbtjatI+X9cKKku/rXJyKeFOb2GS3/lQtlnQZ5PD/RDdGrPOtq25nozehEgNuP7Z XU+UMCB9Qlvf/mWQ2f2fL7az7UnMgg7jjHj2+Ln/DD8qOtHhvTVlmxi9WX851W5fiF gK8X7UWS2mN7FQDzaq64LkhSxA+ur/UvrSQNd34Rev5sq6L+FfrF9z+lbMQaUKHLXo Zaru/KTBSp7/Uj24zhw8IawR7vRcZOdDw0zm8w18pAaYZMYkHLJxcGgJtUPRkRAJOb TPsEzn1E9bRhw== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jonathan Corbet Subject: [PATCH 4/4] docs: remove some index.rst cruft Date: Thu, 1 Sep 2022 17:16:32 -0600 Message-Id: <20220901231632.518583-5-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20220901231632.518583-1-corbet@lwn.net> References: <20220901231632.518583-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" There is some useless boilerplate text that was added by sphinx when this file was first created; take it out. Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/Documentation/index.rst b/Documentation/index.rst index 428cfd8e369b..1e983e3fa6f8 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -1,11 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 =20 - -.. The Linux Kernel documentation master file, created by - sphinx-quickstart on Fri Feb 12 13:51:46 2016. - You can adapt this file completely to your liking, but it should at lea= st - contain the root `toctree` directive. - .. _linux_doc: =20 The Linux Kernel documentation --=20 2.37.2