Documentation/gpu: tables of contents cleanups and fixes
Subsystems (4)
cover Documentation/gpu: tables of contents cleanups and fixes
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(-)
Signature · 1 line
2.47.3
PATCH 1/3 Documentation/gpu: limit main toctree depth to 2
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.
--- Documentation/gpu/index.rst | 1 + 1 file changed, 1 insertion(+)
Documentation/gpu/index.rst +1 -0
@@ -3,6 +3,7 @@ GPU Driver Developer's Guide ============================ .. toctree:: + :maxdepth: 2 introduction drm-internals
Signature · 1 line
2.47.3
Re: [PATCH 1/3] Documentation/gpu: limit main toctree depth to 2
Quoted 10 lines · 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 <[email protected]>
Quoted 16 lines
--- Documentation/gpu/index.rst | 1 + 1 file changed, 1 insertion(+)Documentation/gpu/index.rst +1
-0@@ -3,6 +3,7 @@ GPU Driver Developer's Guide ============================ .. toctree:: + :maxdepth: 2 introduction drm-internals
Signature · 1 line
~Randy
PATCH 2/3 Documentation/gpu: add some tables of contents to large documents
In reply to Jani NikulaSome 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.
--- 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(-)
Documentation/gpu/driver-uapi.rst +2 -0
@@ -2,6 +2,8 @@ DRM Driver uAPI =============== +.. contents:: + drm/i915 uAPI =============
Documentation/gpu/drm-internals.rst +2 -0
@@ -18,6 +18,8 @@ event handling, memory management, output management, framebuffer management, command submission & fencing, suspend/resume support, and DMA services. +.. contents:: + Driver Initialization =====================
Documentation/gpu/drm-kms-helpers.rst +2 -0
@@ -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 ===========================================
Documentation/gpu/drm-kms.rst +2 -0
@@ -15,6 +15,8 @@ be setup by initializing the following fields. - struct drm_mode_config_funcs \*funcs; Mode setting functions. +.. contents:: + Overview ========
Documentation/gpu/drm-mm.rst +2 -0
@@ -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) ===================================
Documentation/gpu/drm-ras.rst +2 -0
@@ -24,6 +24,8 @@ Key Goals: nodes for different IP blocks, sub-blocks, or other logical subdivisions as applicable. +.. contents:: + Nodes =====
Documentation/gpu/drm-uapi.rst +3 -1
@@ -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 + :doc: uAPI trace events
Documentation/gpu/drm-usage-stats.rst +2 -0
@@ -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 =========================
Documentation/gpu/introduction.rst +2 -0
@@ -16,6 +16,8 @@ found in current kernels. [Insert diagram of typical DRM stack here] +.. contents:: + Style Guidelines ================
Signature · 1 line
2.47.3
Re: [PATCH 2/3] Documentation/gpu: add some tables of contents to large documents
Quoted 4 lines · 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.
Quoted 8 lines
The
index.rstin the sub-directories have toctrees, which provide similar overviews.Fix one missing newline at the end of
drm-uapi.rstwhile 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 <[email protected]>
Quoted 136 lines
--- 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(-)Documentation/gpu/driver-uapi.rst +2
-0@@ -2,6 +2,8 @@ DRM Driver uAPI =============== +.. contents:: + drm/i915 uAPI =============Documentation/gpu/drm-internals.rst +2
-0@@ -18,6 +18,8 @@ event handling, memory management, output management, framebuffer management, command submission & fencing, suspend/resume support, and DMA services. +.. contents:: + Driver Initialization =====================Documentation/gpu/drm-kms-helpers.rst +2
-0@@ -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 ===========================================Documentation/gpu/drm-kms.rst +2
-0@@ -15,6 +15,8 @@ be setup by initializing the following fields. - struct drm_mode_config_funcs \*funcs; Mode setting functions. +.. contents:: + Overview ========Documentation/gpu/drm-mm.rst +2
-0@@ -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) ===================================Documentation/gpu/drm-ras.rst +2
-0@@ -24,6 +24,8 @@ Key Goals: nodes for different IP blocks, sub-blocks, or other logical subdivisions as applicable. +.. contents:: + Nodes =====Documentation/gpu/drm-uapi.rst +3
-1@@ -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 + :doc: uAPI trace eventsDocumentation/gpu/drm-usage-stats.rst +2
-0@@ -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 =========================Documentation/gpu/introduction.rst +2
-0@@ -16,6 +16,8 @@ found in current kernels. [Insert diagram of typical DRM stack here] +.. contents:: + Style Guidelines ================
Signature · 1 line
~Randy
PATCH 3/3 Documentation/gpu/rfc: fix toctree
In reply to Jani NikulaJust one toctree is enough. The .rst suffixes are superfluous in the toctree. Fix indent. Add missing newline at the end of the file.
--- Documentation/gpu/rfc/index.rst | 26 ++++++-------------------- 1 file changed, 6 insertions(+), 20 deletions(-)
Documentation/gpu/rfc/index.rst +6 -20
@@ -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 + gpusvm + i915_gem_lmem + i915_scheduler + i915_small_bar + i915_vm_bind + color_pipeline
Signature · 1 line
2.47.3
Re: [PATCH 3/3] Documentation/gpu/rfc: fix toctree
Quoted 4 lines · 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 <[email protected]>
Quoted 39 lines
--- Documentation/gpu/rfc/index.rst | 26 ++++++-------------------- 1 file changed, 6 insertions(+), 20 deletions(-)Documentation/gpu/rfc/index.rst +6
-20@@ -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 + gpusvm + i915_gem_lmem + i915_scheduler + i915_small_bar + i915_vm_bind + color_pipeline
Signature · 1 line
~Randy
Quoted 1 line · Jani Nikula
Make the GPU documentation slightly easier to navigate.
Maxime, Thomas, Maarten, Jon -
Any preferences which tree to merge this through? I'm thinking either drm-misc-next or docs-next.
BR,
Jani.
Quoted 18 lines
Jani Nikula (3):
Documentation/gpu: limit main toctree depth to 2Documentation/gpu: add some tables of contents to large documentsDocumentation/gpu/rfc: fix toctreeDocumentation/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(-)
Signature · 1 line
Jani Nikula, Intel
Jonathan Corbet
maintainerQuoted 7 lines · Jani Nikula
Quoted 1 line · Jani Nikula
Make the GPU documentation slightly easier to navigate.
Maxime, Thomas, Maarten, Jon -
Any preferences which tree to merge this through? I'm thinking either drm-misc-next or docs-next.
Usually I stand back from DRM docs, expecting them to go through the DRM tree. I can certainly pick up this set if that's best, but I wasn't expecting to.
Thanks,
jon
Quoted 5 lines · Jonathan Corbet
Quoted 3 lines · Jani Nikula
Quoted 1 line · Jani Nikula
Make the GPU documentation slightly easier to navigate.
Quoted 8 lines
Quoted 4 lines
Maxime, Thomas, Maarten, Jon -
Any preferences which tree to merge this through? I'm thinking either drm-misc-next or docs-next.
Usually I stand back from DRM docs, expecting them to go through the DRM tree. I can certainly pick up this set if that's best, but I wasn't expecting to.
Thanks. Since I got no reply from the others, and thought this was benign enough, I went ahead and pushed this to drm-misc-next.
Also thanks Randy for having a look at it!
BR,
Jani.
Signature · 1 line
Jani Nikula, Intel