[PATCH v3 2/2] docs: tracing: Reduce maxdepth in index documentation

[PATCH v3 2/2] docs: tracing: Reduce maxdepth in index documentation

[Purva Yeshi]

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

Signed-off-by: Purva Yeshi <purvayeshi550@gmail.com>
---
 Documentation/trace/index.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index 6b268194f..5ddd47ee7 100644
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -14,7 +14,7 @@ This section provides an overview of Linux tracing mechanisms
 and debugging approaches.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    debugging
    tracepoints
@@ -28,7 +28,7 @@ The following are the primary tracing frameworks integrated into
 the Linux kernel.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    ftrace
    ftrace-design
@@ -47,7 +47,7 @@ A detailed explanation of event tracing mechanisms and their
 applications.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    events
    events-kmem
@@ -65,7 +65,7 @@ This section covers tracing features that monitor hardware
 interactions and system performance.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    intel_th
    stm
@@ -85,7 +85,7 @@ These tools allow tracing user-space applications and
 interactions.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    user_events
 
-- 
2.34.1

Re: [PATCH v3 2/2] docs: tracing: Reduce maxdepth in index documentation

[Steven Rostedt]

On Wed, 12 Mar 2025 18:17:17 +0530
Purva Yeshi <purvayeshi550@gmail.com> wrote:

> Reduce :maxdepth: from 2 to 1 in index.rst to simplify the table of
> contents, showing only top-level document titles for better readability.
> 
> Signed-off-by: Purva Yeshi <purvayeshi550@gmail.com>
> ---
>  Documentation/trace/index.rst | 10 +++++-----
>  1 file changed, 5 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
> index 6b268194f..5ddd47ee7 100644
> --- a/Documentation/trace/index.rst
> +++ b/Documentation/trace/index.rst
> @@ -14,7 +14,7 @@ This section provides an overview of Linux tracing mechanisms
>  and debugging approaches.
>  
>  .. toctree::
> -   :maxdepth: 2
> +   :maxdepth: 1

If you made this the first patch, you would only need to modify one place.

This is a patch series. If the end result is going to be maxdepth 1,
you shouldn't add a bunch of maxdepth 2 and then in the next patch make
them all maxdepth 1 as the only change.

Just change the one maxdepth 1 first, and then you can update the code
with the new maxdepth of 1.

-- Steve


>  
>     debugging
>     tracepoints
> @@ -28,7 +28,7 @@ The following are the primary tracing frameworks integrated into
>  the Linux kernel.
>  
>  .. toctree::
> -   :maxdepth: 2
> +   :maxdepth: 1
>  
>     ftrace
>     ftrace-design
> @@ -47,7 +47,7 @@ A detailed explanation of event tracing mechanisms and their
>  applications.
>  
>  .. toctree::
> -   :maxdepth: 2
> +   :maxdepth: 1
>  
>     events
>     events-kmem
> @@ -65,7 +65,7 @@ This section covers tracing features that monitor hardware
>  interactions and system performance.
>  
>  .. toctree::
> -   :maxdepth: 2
> +   :maxdepth: 1
>  
>     intel_th
>     stm
> @@ -85,7 +85,7 @@ These tools allow tracing user-space applications and
>  interactions.
>  
>  .. toctree::
> -   :maxdepth: 2
> +   :maxdepth: 1
>  
>     user_events
>  

Re: [PATCH v3 2/2] docs: tracing: Reduce maxdepth in index documentation

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 1490 bytes --]

On Wed, Mar 12, 2025 at 01:49:07PM -0400, Steven Rostedt wrote:
> On Wed, 12 Mar 2025 18:17:17 +0530
> Purva Yeshi <purvayeshi550@gmail.com> wrote:
> 
> > Reduce :maxdepth: from 2 to 1 in index.rst to simplify the table of
> > contents, showing only top-level document titles for better readability.
> > 
> > Signed-off-by: Purva Yeshi <purvayeshi550@gmail.com>
> > ---
> >  Documentation/trace/index.rst | 10 +++++-----
> >  1 file changed, 5 insertions(+), 5 deletions(-)
> > 
> > diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
> > index 6b268194f..5ddd47ee7 100644
> > --- a/Documentation/trace/index.rst
> > +++ b/Documentation/trace/index.rst
> > @@ -14,7 +14,7 @@ This section provides an overview of Linux tracing mechanisms
> >  and debugging approaches.
> >  
> >  .. toctree::
> > -   :maxdepth: 2
> > +   :maxdepth: 1
> 
> If you made this the first patch, you would only need to modify one place.
> 
> This is a patch series. If the end result is going to be maxdepth 1,
> you shouldn't add a bunch of maxdepth 2 and then in the next patch make
> them all maxdepth 1 as the only change.

If you'd like to generate a patch series, you can refer to thoughtbot
blogpost at [1].

And you can also add cover letter by passing --cover-letter to
git-format-patch(1).

Thanks.

[1]: https://thoughtbot.com/blog/send-a-patch-to-someone-using-git-format-patch

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v3 2/2] docs: tracing: Reduce maxdepth in index documentation

[Steven Rostedt]

On Thu, 13 Mar 2025 10:02:01 +0700
Bagas Sanjaya <bagasdotme@gmail.com> wrote:

> If you'd like to generate a patch series, you can refer to thoughtbot
> blogpost at [1].

??

This is already a patch series.

> 
> And you can also add cover letter by passing --cover-letter to
> git-format-patch(1).

It's simple enough it doesn't need a cover letter.

-- Steve

Re: [PATCH v3 2/2] docs: tracing: Reduce maxdepth in index documentation

[Bagas Sanjaya]

On 3/13/25 18:04, Steven Rostedt wrote:
> On Thu, 13 Mar 2025 10:02:01 +0700
> Bagas Sanjaya <bagasdotme@gmail.com> wrote:
> 
>> If you'd like to generate a patch series, you can refer to thoughtbot
>> blogpost at [1].
> 
> ??
> 
> This is already a patch series.
> 
>>
>> And you can also add cover letter by passing --cover-letter to
>> git-format-patch(1).
> 
> It's simple enough it doesn't need a cover letter.
> 

I mean I'm directing my reply to Purva.

Thanks anyway.

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH v3 2/2] docs: tracing: Reduce maxdepth in index documentation

[Purva Yeshi]

On 12/03/25 23:19, Steven Rostedt wrote:
> On Wed, 12 Mar 2025 18:17:17 +0530
> Purva Yeshi <purvayeshi550@gmail.com> wrote:
> 
>> Reduce :maxdepth: from 2 to 1 in index.rst to simplify the table of
>> contents, showing only top-level document titles for better readability.
>>
>> Signed-off-by: Purva Yeshi <purvayeshi550@gmail.com>
>> ---
>>   Documentation/trace/index.rst | 10 +++++-----
>>   1 file changed, 5 insertions(+), 5 deletions(-)
>>
>> diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
>> index 6b268194f..5ddd47ee7 100644
>> --- a/Documentation/trace/index.rst
>> +++ b/Documentation/trace/index.rst
>> @@ -14,7 +14,7 @@ This section provides an overview of Linux tracing mechanisms
>>   and debugging approaches.
>>   
>>   .. toctree::
>> -   :maxdepth: 2
>> +   :maxdepth: 1
> 
> If you made this the first patch, you would only need to modify one place.
> 
> This is a patch series. If the end result is going to be maxdepth 1,
> you shouldn't add a bunch of maxdepth 2 and then in the next patch make
> them all maxdepth 1 as the only change.
> 
> Just change the one maxdepth 1 first, and then you can update the code
> with the new maxdepth of 1.
> 
> -- Steve

Hi Steven,

Got it. If I understand correctly, you’re suggesting that I reorder the 
patches so that the 'maxdepth' change happens first. That way, I won’t 
introduce maxdepth: 2 only to change it in the next patch. Does that 
sound right?

> 
> 
>>   
>>      debugging
>>      tracepoints
>> @@ -28,7 +28,7 @@ The following are the primary tracing frameworks integrated into
>>   the Linux kernel.
>>   
>>   .. toctree::
>> -   :maxdepth: 2
>> +   :maxdepth: 1
>>   
>>      ftrace
>>      ftrace-design
>> @@ -47,7 +47,7 @@ A detailed explanation of event tracing mechanisms and their
>>   applications.
>>   
>>   .. toctree::
>> -   :maxdepth: 2
>> +   :maxdepth: 1
>>   
>>      events
>>      events-kmem
>> @@ -65,7 +65,7 @@ This section covers tracing features that monitor hardware
>>   interactions and system performance.
>>   
>>   .. toctree::
>> -   :maxdepth: 2
>> +   :maxdepth: 1
>>   
>>      intel_th
>>      stm
>> @@ -85,7 +85,7 @@ These tools allow tracing user-space applications and
>>   interactions.
>>   
>>   .. toctree::
>> -   :maxdepth: 2
>> +   :maxdepth: 1
>>   
>>      user_events
>>   
> 

Re: [PATCH v3 2/2] docs: tracing: Reduce maxdepth in index documentation

[Purva Yeshi]

On 13/03/25 17:46, Bagas Sanjaya wrote:
> On 3/13/25 18:04, Steven Rostedt wrote:
>> On Thu, 13 Mar 2025 10:02:01 +0700
>> Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>>
>>> If you'd like to generate a patch series, you can refer to thoughtbot
>>> blogpost at [1].
>>
>> ??
>>
>> This is already a patch series.
>>
>>>
>>> And you can also add cover letter by passing --cover-letter to
>>> git-format-patch(1).
>>
>> It's simple enough it doesn't need a cover letter.
>>
> 
> I mean I'm directing my reply to Purva.
> 
> Thanks anyway.

Hi Bagas,

Thanks for the reference. I will keep this in mind for future patch 
series and include a cover letter.

> 

Re: [PATCH v3 2/2] docs: tracing: Reduce maxdepth in index documentation

[Steven Rostedt]

On Fri, 14 Mar 2025 14:25:25 +0530
Purva Yeshi <purvayeshi550@gmail.com> wrote:

> Got it. If I understand correctly, you’re suggesting that I reorder the 
> patches so that the 'maxdepth' change happens first. That way, I won’t 
> introduce maxdepth: 2 only to change it in the next patch. Does that 
> sound right?

Exactly!

Thanks,

-- Steev

Re: [PATCH v3 2/2] docs: tracing: Reduce maxdepth in index documentation

[Steven Rostedt]

On Fri, 14 Mar 2025 14:26:37 +0530
Purva Yeshi <purvayeshi550@gmail.com> wrote:

> Thanks for the reference. I will keep this in mind for future patch 
> series and include a cover letter.

Note, a cover letter isn't really necessary here. Why? because these
are pretty much two agnostic patches. One fixes the maxdepth, the other
is changing the layout for readability.

Cover letters are best when there's a bigger picture being had. That
is, the patch series is set out to accomplish a single goal that is
broken up into little steps. A cover letter explains what the goal is
and why and how. Each patch after that explains what that patch is
doing (why and how), but from the focus of that particular change.

As these patches could theoretically be sent as two separate patches
and not as a series as they don't really share the same goal, a cover
letter's only purpose here would be to make the email thread look a
little nicer ;-)  But that's about it.

-- Steve

Re: [PATCH v3 2/2] docs: tracing: Reduce maxdepth in index documentation

[Purva Yeshi]

On 14/03/25 18:11, Steven Rostedt wrote:
> On Fri, 14 Mar 2025 14:26:37 +0530
> Purva Yeshi <purvayeshi550@gmail.com> wrote:
> 
>> Thanks for the reference. I will keep this in mind for future patch
>> series and include a cover letter.
> 
> Note, a cover letter isn't really necessary here. Why? because these
> are pretty much two agnostic patches. One fixes the maxdepth, the other
> is changing the layout for readability.
> 
> Cover letters are best when there's a bigger picture being had. That
> is, the patch series is set out to accomplish a single goal that is
> broken up into little steps. A cover letter explains what the goal is
> and why and how. Each patch after that explains what that patch is
> doing (why and how), but from the focus of that particular change.
> 
> As these patches could theoretically be sent as two separate patches
> and not as a series as they don't really share the same goal, a cover
> letter's only purpose here would be to make the email thread look a 
> little nicer ;-)  But that's about it.
> 
> -- Steve

Got it! Thanks for the clarification Steve.

Best Regards,
Purva Yeshi