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

[Mauro Carvalho Chehab <mchehab@s-opensource.com>]

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