Re: [PATCH 2/3] Documentation/gpu: add some tables of contents to large documents

[Randy Dunlap <rdunlap@infradead.org>]

On 5/8/26 4:12 AM, Jani Nikula wrote:
> Some of the GPU documentation pages are quite long, with various levels
> of details. Add document internal tables of contents to the larger
> documents to make them easier to navigate.
> 
> The index.rst in the sub-directories have toctrees, which provide
> similar overviews.
> 
> Fix one missing newline at the end of drm-uapi.rst while at it,
> primarily because rst should have it, and secondarily because my editor
> rst mode refuses to save the file without it.
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>

Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

> ---
>  Documentation/gpu/driver-uapi.rst     | 2 ++
>  Documentation/gpu/drm-internals.rst   | 2 ++
>  Documentation/gpu/drm-kms-helpers.rst | 2 ++
>  Documentation/gpu/drm-kms.rst         | 2 ++
>  Documentation/gpu/drm-mm.rst          | 2 ++
>  Documentation/gpu/drm-ras.rst         | 2 ++
>  Documentation/gpu/drm-uapi.rst        | 4 +++-
>  Documentation/gpu/drm-usage-stats.rst | 2 ++
>  Documentation/gpu/introduction.rst    | 2 ++
>  9 files changed, 19 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/gpu/driver-uapi.rst b/Documentation/gpu/driver-uapi.rst
> index 1f15a8ca1265..627fc68c7a21 100644
> --- a/Documentation/gpu/driver-uapi.rst
> +++ b/Documentation/gpu/driver-uapi.rst
> @@ -2,6 +2,8 @@
>  DRM Driver uAPI
>  ===============
>  
> +.. contents::
> +
>  drm/i915 uAPI
>  =============
>  
> diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst
> index 94f93fd3b8a0..a3ce25a36f1d 100644
> --- a/Documentation/gpu/drm-internals.rst
> +++ b/Documentation/gpu/drm-internals.rst
> @@ -18,6 +18,8 @@ event handling, memory management, output management, framebuffer
>  management, command submission & fencing, suspend/resume support, and
>  DMA services.
>  
> +.. contents::
> +
>  Driver Initialization
>  =====================
>  
> diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst
> index b4a9e5ae81f6..80453dda33b8 100644
> --- a/Documentation/gpu/drm-kms-helpers.rst
> +++ b/Documentation/gpu/drm-kms-helpers.rst
> @@ -33,6 +33,8 @@ There are a few areas these helpers can grouped into:
>    pipeline: Planes, handling rectangles for visibility checking and scissoring,
>    flip queues and assorted bits.
>  
> +.. contents::
> +
>  Modeset Helper Reference for Common Vtables
>  ===========================================
>  
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index fbe0583eb84c..d22817fdf9aa 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -15,6 +15,8 @@ be setup by initializing the following fields.
>  -  struct drm_mode_config_funcs \*funcs;
>     Mode setting functions.
>  
> +.. contents::
> +
>  Overview
>  ========
>  
> diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
> index 32fb506db05b..2dea94f77d52 100644
> --- a/Documentation/gpu/drm-mm.rst
> +++ b/Documentation/gpu/drm-mm.rst
> @@ -25,6 +25,8 @@ share it. GEM has simpler initialization and execution requirements than
>  TTM, but has no video RAM management capabilities and is thus limited to
>  UMA devices.
>  
> +.. contents::
> +
>  The Translation Table Manager (TTM)
>  ===================================
>  
> diff --git a/Documentation/gpu/drm-ras.rst b/Documentation/gpu/drm-ras.rst
> index 4636e68f5678..83c21853b74b 100644
> --- a/Documentation/gpu/drm-ras.rst
> +++ b/Documentation/gpu/drm-ras.rst
> @@ -24,6 +24,8 @@ Key Goals:
>    nodes for different IP blocks, sub-blocks, or other logical subdivisions
>    as applicable.
>  
> +.. contents::
> +
>  Nodes
>  =====
>  
> diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
> index 32206ce62931..2c2f939322fb 100644
> --- a/Documentation/gpu/drm-uapi.rst
> +++ b/Documentation/gpu/drm-uapi.rst
> @@ -16,6 +16,8 @@ management, and output management.
>  Cover generic ioctls and sysfs layout here. We only need high-level
>  info, since man pages should cover the rest.
>  
> +.. contents::
> +
>  libdrm Device Lookup
>  ====================
>  
> @@ -765,4 +767,4 @@ Stable uAPI events
>  From ``drivers/gpu/drm/scheduler/gpu_scheduler_trace.h``
>  
>  .. kernel-doc::  drivers/gpu/drm/scheduler/gpu_scheduler_trace.h
> -   :doc: uAPI trace events
> \ No newline at end of file
> +   :doc: uAPI trace events
> diff --git a/Documentation/gpu/drm-usage-stats.rst b/Documentation/gpu/drm-usage-stats.rst
> index 24d3012ca7a6..70b7cfcc194f 100644
> --- a/Documentation/gpu/drm-usage-stats.rst
> +++ b/Documentation/gpu/drm-usage-stats.rst
> @@ -16,6 +16,8 @@ output is split between common and driver specific parts. Having said that,
>  wherever possible effort should still be made to standardise as much as
>  possible.
>  
> +.. contents::
> +
>  File format specification
>  =========================
>  
> diff --git a/Documentation/gpu/introduction.rst b/Documentation/gpu/introduction.rst
> index d8f519693fc2..64074ac22d9b 100644
> --- a/Documentation/gpu/introduction.rst
> +++ b/Documentation/gpu/introduction.rst
> @@ -16,6 +16,8 @@ found in current kernels.
>  
>  [Insert diagram of typical DRM stack here]
>  
> +.. contents::
> +
>  Style Guidelines
>  ================
>  

-- 
~Randy