[01/11] docs: Tweak the top-level Sphinx page

Message ID 1477523979-5837-2-git-send-email-corbet@lwn.net
State New
Headers show

Commit Message

Jonathan Corbet Oct. 26, 2016, 11:19 p.m.
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.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>

---
 Documentation/index.rst | 45 +++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 41 insertions(+), 4 deletions(-)

-- 
2.7.4

Comments

Mauro Carvalho Chehab Oct. 27, 2016, 12:12 a.m. | #1
Em Wed, 26 Oct 2016 17:19:29 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

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

> 

> Signed-off-by: Jonathan Corbet <corbet@lwn.net>


Looks great!

Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>


> ---

>  Documentation/index.rst | 45 +++++++++++++++++++++++++++++++++++++++++----

>  1 file changed, 41 insertions(+), 4 deletions(-)

> 

> diff --git a/Documentation/index.rst b/Documentation/index.rst

> index f6a3d4766495..7cec8432ce7a 100644

> --- a/Documentation/index.rst

> +++ b/Documentation/index.rst

> @@ -3,18 +3,55 @@

>     You can adapt this file completely to your liking, but it should at least

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

>     :maxdepth: 2

>  

>     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

>     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

>     media/index

>     gpu/index




Thanks,
Mauro

Patch

diff --git a/Documentation/index.rst b/Documentation/index.rst
index f6a3d4766495..7cec8432ce7a 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -3,18 +3,55 @@ 
    You can adapt this file completely to your liking, but it should at least
    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::
    :maxdepth: 2
 
    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
    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
    media/index
    gpu/index