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 <[email protected]>
---
Documentation/index.rst | 150 +++++++++++--------------------
Documentation/subsystem-apis.rst | 58 ++++++++++++
2 files changed, 111 insertions(+), 97 deletions(-)
create mode 100644 Documentation/subsystem-apis.rst
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 4737c18c97ff..e0b593486e7d 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -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
@@ -150,7 +107,7 @@ Architecture-specific documentation
-----------------------------------
.. toctree::
- :maxdepth: 2
+ :maxdepth: 1
arch
@@ -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
diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst
new file mode 100644
index 000000000000..af65004a80aa
--- /dev/null
+++ b/Documentation/subsystem-apis.rst
@@ -0,0 +1,58 @@
+.. 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
--
2.37.2
Randy Dunlap <[email protected]> writes:
> Hi Jonathan,
>
> On 9/22/22 13:41, Jonathan Corbet wrote:
>> 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 <[email protected]>
>> ---
>> Documentation/index.rst | 150 +++++++++++--------------------
>> Documentation/subsystem-apis.rst | 58 ++++++++++++
>> 2 files changed, 111 insertions(+), 97 deletions(-)
>> create mode 100644 Documentation/subsystem-apis.rst
>
> I don't see a kernel version listed anywhere on the front page
> (maybe it depends on what theme is used?) at
> https://static.lwn.net/kerneldoc/, so I think it needs something like
> this.
>
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -18,6 +18,8 @@ documents into a coherent whole. Please
> documentation are welcome; join the linux-doc list at vger.kernel.org if
> you want to help out.
>
> +This documentation is for Linux kernel $(KERNELRELEASE).
> +
Ah, it does look like we lost that in the transition; I'll make sure it
gets put back.
Thanks,
jon
Hi Jonathan,
On 9/22/22 13:41, Jonathan Corbet wrote:
> 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 <[email protected]>
> ---
> Documentation/index.rst | 150 +++++++++++--------------------
> Documentation/subsystem-apis.rst | 58 ++++++++++++
> 2 files changed, 111 insertions(+), 97 deletions(-)
> create mode 100644 Documentation/subsystem-apis.rst
I don't see a kernel version listed anywhere on the front page
(maybe it depends on what theme is used?) at
https://static.lwn.net/kerneldoc/, so I think it needs something like
this.
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -18,6 +18,8 @@ documents into a coherent whole. Please
documentation are welcome; join the linux-doc list at vger.kernel.org if
you want to help out.
+This documentation is for Linux kernel $(KERNELRELEASE).
+
Licensing documentation
-----------------------
The line numbering is probably off a bit, but the big problem is in
using $(KERNELRELEASE). Would using $(version) [with 'version' coming
from conf.py] work here? Nope, that doesn't work either.
--
~Randy
On Thu, Sep 22, 2022 at 02:41:33PM -0600, Jonathan Corbet wrote:
> 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 <[email protected]>
Reviewed-by: David Vernet <[email protected]>