Browse Source

docs: Tweak the top-level Sphinx page

This will be the initial landing point for readers, so give them a bit of
introductory material.  Also split the TOC into area-specific chunks to
make the whole thing a bit more approachable.

Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet 8 years ago
parent
commit
b51208d41c
1 changed files with 41 additions and 4 deletions
  1. 41 4
      Documentation/index.rst

+ 41 - 4
Documentation/index.rst

@@ -3,18 +3,55 @@
    You can adapt this file completely to your liking, but it should at least
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
    contain the root `toctree` directive.
 
 
-Welcome to The Linux Kernel's documentation!
-============================================
+Welcome to The Linux Kernel's documentation
+===========================================
 
 
-Contents:
+This is the top level of the kernel's documentation tree.  Kernel
+documentation, like the kernel itself, is very much a work in progress;
+that is especially true as we work to integrate our many scattered
+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.
+
+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.
 
 
 .. toctree::
 .. toctree::
    :maxdepth: 2
    :maxdepth: 2
 
 
    admin-guide/index
    admin-guide/index
-   kernel-documentation
+
+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.
+
+.. toctree::
+   :maxdepth: 2
+
    process/index
    process/index
    dev-tools/tools
    dev-tools/tools
+   kernel-documentation
+
+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 — probably *not* all that is
+needed). 
+
+.. toctree::
+   :maxdepth: 2
+
    driver-api/index
    driver-api/index
    media/index
    media/index
    gpu/index
    gpu/index