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

[Purva Yeshi <purvayeshi550@gmail.com>]

On 13/02/25 22:17, Steven Rostedt wrote:
> On Thu, 13 Feb 2025 17:26:21 +0530
> Purva Yeshi <purvayeshi550@gmail.com> wrote:
> 
>>>> +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.

> 
>>>>    
>>>> -   ftrace-design
>>>> +   debugging
>>>> +   tracepoints
>>>>       tracepoint-analysis
>>>> +
> 
>>>> +
>>>> +Hardware and Performance Tracing
>>>> +--------------------------------
>>>> +
>>>> +This section covers tracing features that monitor hardware
>>>> +interactions and system performance.
>>>> +
>>>> +.. toctree::
>>>> +   :maxdepth: 1
>>>> +
>>>>       intel_th
>>>    
>>>>       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.
>>
>>>>       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.