[PATCH 0/3] Documentation/gpu: tables of contents cleanups and fixes

[PATCH 0/3] Documentation/gpu: tables of contents cleanups and fixes

[Jani Nikula]

Make the GPU documentation slightly easier to navigate.

Jani Nikula (3):
  Documentation/gpu: limit main toctree depth to 2
  Documentation/gpu: add some tables of contents to large documents
  Documentation/gpu/rfc: fix toctree

 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/index.rst           |  1 +
 Documentation/gpu/introduction.rst    |  2 ++
 Documentation/gpu/rfc/index.rst       | 26 ++++++--------------------
 11 files changed, 26 insertions(+), 21 deletions(-)

-- 
2.47.3

[PATCH 1/3] Documentation/gpu: limit main toctree depth to 2

[Jani Nikula]

The main GPU documentation toctree has no limit to the toctree depth,
which means the main GPU index page recursively includes all the
headings in all of GPU documentation in the single table of
contents. This makes getting any kind of overview of the documentation
really difficult.

Limit the main toctree depth to 2 i.e. show at most two levels of
headings.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 Documentation/gpu/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
index 5d708a106b3f..65bf3b26e4f4 100644
--- a/Documentation/gpu/index.rst
+++ b/Documentation/gpu/index.rst
@@ -3,6 +3,7 @@ GPU Driver Developer's Guide
 ============================
 
 .. toctree::
+   :maxdepth: 2
 
    introduction
    drm-internals
-- 
2.47.3

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

[Jani Nikula]

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>
---
 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
 ================
 
-- 
2.47.3

[PATCH 3/3] Documentation/gpu/rfc: fix toctree

[Jani Nikula]

Just one toctree is enough. The .rst suffixes are superfluous in the
toctree. Fix indent. Add missing newline at the end of the file.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 Documentation/gpu/rfc/index.rst | 26 ++++++--------------------
 1 file changed, 6 insertions(+), 20 deletions(-)

diff --git a/Documentation/gpu/rfc/index.rst b/Documentation/gpu/rfc/index.rst
index ef19b0ba2a3e..26a7ebe6fb44 100644
--- a/Documentation/gpu/rfc/index.rst
+++ b/Documentation/gpu/rfc/index.rst
@@ -18,23 +18,9 @@ host such documentation:
 
 .. toctree::
 
-    gpusvm.rst
-
-.. toctree::
-
-    i915_gem_lmem.rst
-
-.. toctree::
-
-    i915_scheduler.rst
-
-.. toctree::
-
-    i915_small_bar.rst
-
-.. toctree::
-
-    i915_vm_bind.rst
-
-.. toctree::
-    color_pipeline.rst
\ No newline at end of file
+   gpusvm
+   i915_gem_lmem
+   i915_scheduler
+   i915_small_bar
+   i915_vm_bind
+   color_pipeline
-- 
2.47.3

Re: [PATCH 3/3] Documentation/gpu/rfc: fix toctree

[Randy Dunlap]

On 5/8/26 4:12 AM, Jani Nikula wrote:
> Just one toctree is enough. The .rst suffixes are superfluous in the
> toctree. Fix indent. Add missing newline at the end of the file.
> 
> 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/rfc/index.rst | 26 ++++++--------------------
>  1 file changed, 6 insertions(+), 20 deletions(-)
> 
> diff --git a/Documentation/gpu/rfc/index.rst b/Documentation/gpu/rfc/index.rst
> index ef19b0ba2a3e..26a7ebe6fb44 100644
> --- a/Documentation/gpu/rfc/index.rst
> +++ b/Documentation/gpu/rfc/index.rst
> @@ -18,23 +18,9 @@ host such documentation:
>  
>  .. toctree::
>  
> -    gpusvm.rst
> -
> -.. toctree::
> -
> -    i915_gem_lmem.rst
> -
> -.. toctree::
> -
> -    i915_scheduler.rst
> -
> -.. toctree::
> -
> -    i915_small_bar.rst
> -
> -.. toctree::
> -
> -    i915_vm_bind.rst
> -
> -.. toctree::
> -    color_pipeline.rst
> \ No newline at end of file
> +   gpusvm
> +   i915_gem_lmem
> +   i915_scheduler
> +   i915_small_bar
> +   i915_vm_bind
> +   color_pipeline

-- 
~Randy

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

[Randy Dunlap]

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

Re: [PATCH 1/3] Documentation/gpu: limit main toctree depth to 2

[Randy Dunlap]

On 5/8/26 4:12 AM, Jani Nikula wrote:
> The main GPU documentation toctree has no limit to the toctree depth,
> which means the main GPU index page recursively includes all the
> headings in all of GPU documentation in the single table of
> contents. This makes getting any kind of overview of the documentation
> really difficult.
> 
> Limit the main toctree depth to 2 i.e. show at most two levels of
> headings.
> 
> 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/index.rst | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
> index 5d708a106b3f..65bf3b26e4f4 100644
> --- a/Documentation/gpu/index.rst
> +++ b/Documentation/gpu/index.rst
> @@ -3,6 +3,7 @@ GPU Driver Developer's Guide
>  ============================
>  
>  .. toctree::
> +   :maxdepth: 2
>  
>     introduction
>     drm-internals

-- 
~Randy