diff mbox series

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

Message ID 20250312124717.7208-1-purvayeshi550@gmail.com (mailing list archive)
State New
Headers show
Series [v3,1/2] docs: tracing: Refactor index.rst documentation | expand

Commit Message

Purva Yeshi March 12, 2025, 12:47 p.m. UTC
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(-)

Comments

Steven Rostedt March 12, 2025, 5:49 p.m. UTC | #1
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
>
Bagas Sanjaya March 13, 2025, 3:02 a.m. UTC | #2
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
Steven Rostedt March 13, 2025, 11:04 a.m. UTC | #3
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
Bagas Sanjaya March 13, 2025, 12:16 p.m. UTC | #4
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.
Purva Yeshi March 14, 2025, 8:55 a.m. UTC | #5
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
>>   
>
Purva Yeshi March 14, 2025, 8:56 a.m. UTC | #6
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.

>
Steven Rostedt March 14, 2025, 12:35 p.m. UTC | #7
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
Steven Rostedt March 14, 2025, 12:41 p.m. UTC | #8
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
diff mbox series

Patch

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