Re: [PATCH v2] docs: trace: Refactor index documentation

On Thu, 13 Feb 2025 17:26:21 +0530
Purva Yeshi [off-list ref] wrote:

quoted

quoted

+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: 2
+   :maxdepth: 1  

I don't really know what the maxdepth gives here, but there was no mention
in the change log why it had to be converted from 2 to 1.
  

I changed :maxdepth: from 2 to 1 to simplify the table of contents, 
keeping only document titles instead of also including second-level 
section headings. The intent was to improve readability and navigation.

Additionally, I referred to commit '270beb5b2aae', as suggested by 
Jonathan Corbet in the v1 patch, to align the documentation structure 
accordingly.

I'll update the commit message in the next revision to explicitly 
mention this change.

Can you make that a separate patch. A commit should do only one thing and
that change isn't necessary to be part of the rest of the changes.

quoted

quoted

  
-   ftrace-design
+   debugging
+   tracepoints
     tracepoint-analysis
+

quoted

quoted

+
+Hardware and Performance Tracing
+--------------------------------
+
+This section covers tracing features that monitor hardware
+interactions and system performance.
+
+.. toctree::
+   :maxdepth: 1
+
     intel_th  

quoted

     ring-buffer-design  

The ring-buffer-design should be in "Core Tracing Frameworks".
  

I'll move 'ring-buffer-design' to the Core Tracing Frameworks section.

quoted

quoted

     ring-buffer-map  

This describes how to map the ring buffer in user space. Maybe it should go
at the "Introduction" section?

  

For ring-buffer-map, placing it in the Introduction section could 
provide early context, but since it is more implementation-specific, it 
might fit better under Core Tracing Frameworks alongside 
ring-buffer-design. Would that placement works?

But it's not kernel implementation. It describes how to use it in user
space. That is, it's not part of the tracing framework.

-- Steve