Commit 0c7b4366 authored by Jonathan Corbet's avatar Jonathan Corbet
Browse files

docs: Rewrite the front page 



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.

Acked-by: default avatarJani Nikula <jani.nikula@intel.com>
Reviewed-by: default avatarDavid Vernet <void@manifault.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
Acked-by: default avatarRandy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20220927160559.97154-3-corbet@lwn.net


Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 9d0f5cd1

Documentation/index.rst

+52 −96
Original line number Diff line number Diff line
@@ -18,131 +18,88 @@ documents into a coherent whole. Please note that improvements to the 
documentation are welcome; join the linux-doc list at vger.kernel.org if

you want to help out.



Licensing documentation

-----------------------

Working with the development community

--------------------------------------



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.



* :ref:`kernel_licensing`



User-oriented documentation

---------------------------



The following manuals are written for *users* of the kernel — those who are

trying to get it to work optimally on a given system.

The essential guides for interacting with the kernel's development

community and getting your work upstream.



.. toctree::

   :maxdepth: 2



   admin-guide/index

   kbuild/index



Firmware-related documentation

------------------------------

The following holds information on the kernel's expectations regarding the

platform firmwares.

   :maxdepth: 1



.. toctree::

   :maxdepth: 2

   process/development-process

   process/submitting-patches

   Code of conduct <process/code-of-conduct>

   maintainer/index

   All development-process docs <process/index>



   firmware-guide/index

   devicetree/index



Application-developer documentation

-----------------------------------

Internal API manuals

--------------------



The user-space API manual gathers together documents describing aspects of

the kernel interface as seen by application developers.

Manuals for use by developers working to interface with the rest of the

kernel.



.. toctree::

   :maxdepth: 2



   userspace-api/index

   :maxdepth: 1



   core-api/index

   driver-api/index

   subsystem-apis

   Locking in the kernel <locking/index>



Introduction to kernel development

----------------------------------

Development tools and processes

-------------------------------



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.

Various other manuals with useful information for all kernel developers.



.. toctree::

   :maxdepth: 2

   :maxdepth: 1



   process/index

   dev-tools/index

   process/license-rules

   doc-guide/index

   dev-tools/index

   dev-tools/testing-overview

   kernel-hacking/index

   trace/index

   maintainer/index

   fault-injection/index

   livepatch/index





Kernel API documentation

------------------------

User-oriented 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 — probably *not* all that is

needed).

The following manuals are written for *users* of the kernel — those who are

trying to get it to work optimally on a given system and application

developers seeking information on the kernel's user-space APIs.



.. toctree::

   :maxdepth: 2

   :maxdepth: 1



   admin-guide/index

   The kernel build system <kbuild/index>

   admin-guide/reporting-issues.rst

   User-space tools <tools/index>

   userspace-api/index





Firmware-related documentation

------------------------------

The following holds information on the kernel's expectations regarding the

platform firmwares.



.. toctree::

   :maxdepth: 1



   firmware-guide/index

   devicetree/index



   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



Architecture-agnostic documentation

-----------------------------------



.. toctree::

   :maxdepth: 2

   :maxdepth: 1



   asm-annotations
@@ -163,9 +120,8 @@ of the documentation body, or may require some adjustments and/or conversion 
to ReStructured Text format, or are simply too old.



.. toctree::

   :maxdepth: 2

   :maxdepth: 1



   tools/index

   staging/index

Documentation/subsystem-apis.rst

0 → 100644
+58 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



==============================

Kernel subsystem 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 — probably *not* all that is

needed).



**Fixme**: much more organizational work is needed here.



.. 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