Skip to contentSkip to conversation

docs: tracing: Reduce maxdepth in index.rst for clarity

PATCH In review Purva Yeshi 3 participants 6 messages Mar 18, 2025 – Apr 8, 2025

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH v4 1/2 docs: tracing: Reduce maxdepth in index.rst for clarity

Reduce :maxdepth: from 2 to 1 in index.rst to simplify the table of contents, showing only top-level document titles for better readability.

---
V1 - https://lore.kernel.org/all/[email protected]/
V2 - https://lore.kernel.org/lkml/[email protected]/
V3 - https://lore.kernel.org/all/[email protected]/
V4 - Reorder patches to apply the 'maxdepth' change first, then refactor the index documentation to avoid introducing maxdepth: 2 only to modify it in the next patch.

 Documentation/trace/index.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/trace/index.rst +1 -1
index 2c991dc96..fecc4adf7 100644
@@ -3,7 +3,7 @@ Linux Tracing Technologies
 ==========================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    ftrace-design
    tracepoint-analysis
Signature · 1 line
2.34.1
#1 lore raw

PATCH v4 2/2 docs: tracing: Refactor index.rst for clarity

Refactor Documentation/trace/index.rst to improve clarity, structure, and organization. Reformat sections and add appropriate headings for better readability.

Improve section grouping and refine descriptions for better usability.

---
 Documentation/trace/index.rst | 94 +++++++++++++++++++++++++++++------
 1 file changed, 79 insertions(+), 15 deletions(-)
Documentation/trace/index.rst +79 -15
index fecc4adf7..5ddd47ee7 100644
@@ -1,39 +1,103 @@
-==========================
-Linux Tracing Technologies
-==========================
+================================
+Linux Tracing Technologies Guide
+================================
+
+Tracing in the Linux kernel is a powerful mechanism that allows
+developers and system administrators to analyze and debug system
+behavior. This guide provides documentation on various tracing
+frameworks and tools available in the Linux kernel.
+
+Introduction to Tracing
+-----------------------
+
+This section provides an overview of Linux tracing mechanisms
+and debugging approaches.
 
 .. toctree::
    :maxdepth: 1
 
-   ftrace-design
+   debugging
+   tracepoints
    tracepoint-analysis
+   ring-buffer-map
+
+Core Tracing Frameworks
+-----------------------
+
+The following are the primary tracing frameworks integrated into
+the Linux kernel.
+
+.. toctree::
+   :maxdepth: 1
+
    ftrace
+   ftrace-design
    ftrace-uses
-   fprobe
    kprobes
    kprobetrace
    uprobetracer
    fprobetrace
-   tracepoints
+   fprobe
+   ring-buffer-design
+
+Event Tracing and Analysis
+--------------------------
+
+A detailed explanation of event tracing mechanisms and their
+applications.
+
+.. toctree::
+   :maxdepth: 1
+
    events
    events-kmem
    events-power
    events-nmi
    events-msr
-   mmiotrace
+   boottime-trace
    histogram
    histogram-design
-   boottime-trace
-   debugging
-   hwlat_detector
-   osnoise-tracer
-   timerlat-tracer
+
+Hardware and Performance Tracing
+--------------------------------
+
+This section covers tracing features that monitor hardware
+interactions and system performance.
+
+.. toctree::
+   :maxdepth: 1
+
    intel_th
-   ring-buffer-design
-   ring-buffer-map
    stm
    sys-t
    coresight/index
-   user_events
    rv/index
    hisi-ptt
+   mmiotrace
+   hwlat_detector
+   osnoise-tracer
+   timerlat-tracer
+
+User-Space Tracing
+------------------
+
+These tools allow tracing user-space applications and
+interactions.
+
+.. toctree::
+   :maxdepth: 1
+
+   user_events
+
+Additional Resources
+--------------------
+
+For more details, refer to the respective documentation of each
+tracing tool and framework.
+
+.. only:: subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
\ No newline at end of file
Signature · 1 line
2.34.1
Reviewed-by on v4 2/2
#2 lore raw

Re: [PATCH v4 2/2] docs: tracing: Refactor index.rst for clarity

Quoted 114 lines · Purva Yeshi
Documentation/trace/index.rst +70 -15
index fecc4adf7..5ddd47ee7 100644
@@ -1,39 +1,103 @@
-==========================
-Linux Tracing Technologies
-==========================
+================================
+Linux Tracing Technologies Guide
+================================
+
+Tracing in the Linux kernel is a powerful mechanism that allows
+developers and system administrators to analyze and debug system
+behavior. This guide provides documentation on various tracing
+frameworks and tools available in the Linux kernel.
+
+Introduction to Tracing
+-----------------------
+
+This section provides an overview of Linux tracing mechanisms
+and debugging approaches.
 
 .. toctree::
    :maxdepth: 1
 
-   ftrace-design
+   debugging
+   tracepoints
    tracepoint-analysis
+   ring-buffer-map
+
+Core Tracing Frameworks
+-----------------------
+
+The following are the primary tracing frameworks integrated into
+the Linux kernel.
+
+.. toctree::
+   :maxdepth: 1
+
    ftrace
+   ftrace-design
    ftrace-uses
-   fprobe
    kprobes
    kprobetrace
    uprobetracer
    fprobetrace
-   tracepoints
+   fprobe
+   ring-buffer-design
+
+Event Tracing and Analysis
+--------------------------
+
+A detailed explanation of event tracing mechanisms and their
+applications.
+
+.. toctree::
+   :maxdepth: 1
+
    events
    events-kmem
    events-power
    events-nmi
    events-msr
-   mmiotrace
+   boottime-trace
    histogram
    histogram-design
-   boottime-trace
-   debugging
-   hwlat_detector
-   osnoise-tracer
-   timerlat-tracer
+
+Hardware and Performance Tracing
+--------------------------------
+
+This section covers tracing features that monitor hardware
+interactions and system performance.
+
+.. toctree::
+   :maxdepth: 1
+
    intel_th
-   ring-buffer-design
-   ring-buffer-map
    stm
    sys-t
    coresight/index
-   user_events
    rv/index
    hisi-ptt
+   mmiotrace
+   hwlat_detector
+   osnoise-tracer
+   timerlat-tracer
+
+User-Space Tracing
+------------------
+
+These tools allow tracing user-space applications and
+interactions.
+
+.. toctree::
+   :maxdepth: 1
+
+   user_events
+
+Additional Resources
+--------------------
+

Documentation/trace/index.rst line 103

Quoted 10 lines
Documentation/trace/index.rst +9 -0
+For more details, refer to the respective documentation of each
+tracing tool and framework.
+
+.. only:: subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
\ No newline at end of file

LGTM, thanks!

Signature · 1 line
An old man doll... just what I always wanted! - Clara
maintainer Acked-by Steven Rostedt (Google) on v4 2/2
#3 lore raw

Re: [PATCH v4 2/2] docs: tracing: Refactor index.rst for clarity

In reply to Purva Yeshi
Quoted 10 lines · On Tue, 18 Mar 2025 17:02:30 +0530 Purva Yeshi <[email protected]> wrote:

Refactor Documentation/trace/index.rst to improve clarity, structure, and organization. Reformat sections and add appropriate headings for better readability.

Improve section grouping and refine descriptions for better usability.

---
 Documentation/trace/index.rst | 94 +++++++++++++++++++++++++++++------
 1 file changed, 79 insertions(+), 15 deletions(-)

For both patches:

Jon,

Feel free to apply these to your tree.

Thanks,

-- Steve

#4 lore raw

Re: [PATCH v4 2/2] docs: tracing: Refactor index.rst for clarity

Quoted 3 lines · Steven Rostedt

Jon,

Feel free to apply these to your tree.

Hi Jon,

It seems like this series didn't make it to 6.15 merge window. What about applying it on current cycle (for 6.16) instead? Or should I carry and resubmit it?

Thanks.

Signature · 1 line
An old man doll... just what I always wanted! - Clara
Reviewed-by on v4 1/2
#5 lore raw
In reply to Purva Yeshi

Documentation/trace/index.rst Linux Tracing Technologies · line 9

Quoted 13 lines · Purva Yeshi
Documentation/trace/index.rst +1 -1
index 2c991dc96..fecc4adf7 100644
@@ -3,7 +3,7 @@ Linux Tracing Technologies
 ==========================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    ftrace-design
    tracepoint-analysis

LGTM, thanks!

Signature · 1 line
An old man doll... just what I always wanted! - Clara