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

On 13/02/25 22:17, Steven Rostedt wrote:

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

quoted

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.

Okay, I’ll separate this change into a new patch.

quoted

quoted

quoted

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

quoted

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

Thanks for the clarification. I’ll move it to the Introduction section 
in the next revision.