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 |
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 >
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
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
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.
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 >> >
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. >
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
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 --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
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(-)