[PATCH] docs: fix WARNING document not included in any toctree

[PATCH] docs: fix WARNING document not included in any toctree

[SurajSonawane2415]

Add debugging.rst to the relevant toctree to fix warning
about missing documentation inclusion in toctree.

Signed-off-by: SurajSonawane2415 <surajsonawane0215@gmail.com>
---
 Documentation/trace/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index 0b300901f..2c991dc96 100644
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -24,6 +24,7 @@ Linux Tracing Technologies
    histogram
    histogram-design
    boottime-trace
+   debugging
    hwlat_detector
    osnoise-tracer
    timerlat-tracer
-- 
2.34.1

Re: [PATCH] docs: fix WARNING document not included in any toctree

[Jonathan Corbet]

SurajSonawane2415 <surajsonawane0215@gmail.com> writes:

> Add debugging.rst to the relevant toctree to fix warning
> about missing documentation inclusion in toctree.
>
> Signed-off-by: SurajSonawane2415 <surajsonawane0215@gmail.com>
> ---
>  Documentation/trace/index.rst | 1 +
>  1 file changed, 1 insertion(+)
>
> diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
> index 0b300901f..2c991dc96 100644
> --- a/Documentation/trace/index.rst
> +++ b/Documentation/trace/index.rst
> @@ -24,6 +24,7 @@ Linux Tracing Technologies
>     histogram
>     histogram-design
>     boottime-trace
> +   debugging
>     hwlat_detector

Applied, thanks.

For future reference, please use your proper name in your signed-off-by
line.

jon

Re: [PATCH] docs: fix WARNING document not included in any toctree

[Steven Rostedt]

On Thu,  3 Oct 2024 01:28:17 +0530
SurajSonawane2415 <surajsonawane0215@gmail.com> wrote:

> Add debugging.rst to the relevant toctree to fix warning
> about missing documentation inclusion in toctree.
> 
> Signed-off-by: SurajSonawane2415 <surajsonawane0215@gmail.com>
> ---
>  Documentation/trace/index.rst | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
> index 0b300901f..2c991dc96 100644
> --- a/Documentation/trace/index.rst
> +++ b/Documentation/trace/index.rst
> @@ -24,6 +24,7 @@ Linux Tracing Technologies
>     histogram
>     histogram-design
>     boottime-trace
> +   debugging

If order matters here, I'd like the debugging to be at the top. As I plan
on it being more of a tutorial for using tracing, and should be the first
document people see.

I need to take some time out and start filling it up!

-- Steve


>     hwlat_detector
>     osnoise-tracer
>     timerlat-tracer

Re: [PATCH] docs: fix WARNING document not included in any toctree

[Jonathan Corbet]

Steven Rostedt <rostedt@goodmis.org> writes:

> On Thu,  3 Oct 2024 01:28:17 +0530
> SurajSonawane2415 <surajsonawane0215@gmail.com> wrote:
>
>> Add debugging.rst to the relevant toctree to fix warning
>> about missing documentation inclusion in toctree.
>> 
>> Signed-off-by: SurajSonawane2415 <surajsonawane0215@gmail.com>
>> ---
>>  Documentation/trace/index.rst | 1 +
>>  1 file changed, 1 insertion(+)
>> 
>> diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
>> index 0b300901f..2c991dc96 100644
>> --- a/Documentation/trace/index.rst
>> +++ b/Documentation/trace/index.rst
>> @@ -24,6 +24,7 @@ Linux Tracing Technologies
>>     histogram
>>     histogram-design
>>     boottime-trace
>> +   debugging
>
> If order matters here, I'd like the debugging to be at the top. As I plan
> on it being more of a tutorial for using tracing, and should be the first
> document people see.
>
> I need to take some time out and start filling it up!

That's the order that the links will show up in the rendered page, so
yes, it matters.

jon

Re: [PATCH] docs: fix WARNING document not included in any toctree

[Suraj Sonawane]

On 11/10/24 01:21, Jonathan Corbet wrote:
> Steven Rostedt <rostedt@goodmis.org> writes:
> 
>> On Thu,  3 Oct 2024 01:28:17 +0530
>> SurajSonawane2415 <surajsonawane0215@gmail.com> wrote:
>>
>>> Add debugging.rst to the relevant toctree to fix warning
>>> about missing documentation inclusion in toctree.
>>>
>>> Signed-off-by: SurajSonawane2415 <surajsonawane0215@gmail.com>
>>> ---
>>>   Documentation/trace/index.rst | 1 +
>>>   1 file changed, 1 insertion(+)
>>>
>>> diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
>>> index 0b300901f..2c991dc96 100644
>>> --- a/Documentation/trace/index.rst
>>> +++ b/Documentation/trace/index.rst
>>> @@ -24,6 +24,7 @@ Linux Tracing Technologies
>>>      histogram
>>>      histogram-design
>>>      boottime-trace
>>> +   debugging
>>
>> If order matters here, I'd like the debugging to be at the top. As I plan
>> on it being more of a tutorial for using tracing, and should be the first
>> document people see.
>>

Thanks for the feedback!

>> I need to take some time out and start filling it up!
> 
> That's the order that the links will show up in the rendered page, so
> yes, it matters.
> 
> jon
Can I send an updated patch with this change (moving debugging section 
to the top)?

Best,
Suraj

Re: [PATCH] docs: fix WARNING document not included in any toctree

[Jonathan Corbet]

Suraj Sonawane <surajsonawane0215@gmail.com> writes:

> Can I send an updated patch with this change (moving debugging section 
> to the top)?

The patch is already applied, so no.  You can send a new patch against
docs-next if that sort of movement is warranted.

Honestly, though, just shuffling one file around only seems so useful.
What would be nice would be to turn index.rst into a good starting point
for people wanting to learn about tracing, rather than just a jumble of
files.  It needs organization into sections and some connecting text; as
an example, see the (minimal) organizational work that I did for
Documentation/process/index.rst. 

It's more work, but would certainly pay off.

Thanks,

jon

Re: [PATCH] docs: fix WARNING document not included in any toctree

[Steven Rostedt]

On Fri, 11 Oct 2024 07:28:40 -0600
Jonathan Corbet <corbet@lwn.net> wrote:

> Suraj Sonawane <surajsonawane0215@gmail.com> writes:
> 
> > Can I send an updated patch with this change (moving debugging section 
> > to the top)?  
> 
> The patch is already applied, so no.  You can send a new patch against
> docs-next if that sort of movement is warranted.
> 
> Honestly, though, just shuffling one file around only seems so useful.
> What would be nice would be to turn index.rst into a good starting point
> for people wanting to learn about tracing, rather than just a jumble of
> files.  It needs organization into sections and some connecting text; as
> an example, see the (minimal) organizational work that I did for
> Documentation/process/index.rst. 
> 
> It's more work, but would certainly pay off.

I'm still new to how the Documentation directory is set up. But I agree
with Jon. It's been on my todo list to make the tracing directory more of a
tutorial. I just need to find the time to do so.

-- Steve

Re: [PATCH] docs: fix WARNING document not included in any toctree

[Suraj Sonawane]

On 11/10/24 18:58, Jonathan Corbet wrote:
> Suraj Sonawane <surajsonawane0215@gmail.com> writes:
> 
>> Can I send an updated patch with this change (moving debugging section
>> to the top)?
> 
> The patch is already applied, so no.  You can send a new patch against
> docs-next if that sort of movement is warranted.

Sure! I will send a patch against docs-next to move the debugging 
section to the top.

> 
> Honestly, though, just shuffling one file around only seems so useful.
> What would be nice would be to turn index.rst into a good starting point
> for people wanting to learn about tracing, rather than just a jumble of
> files.  It needs organization into sections and some connecting text; as
> an example, see the (minimal) organizational work that I did for
> Documentation/process/index.rst.
> 
> It's more work, but would certainly pay off.
> 
> Thanks,
> 
> jon

I’ve also seen the structure in Documentation/process/index.rst with the 
clear titles and descriptions.

Thanks,
Suraj Sonawane