Re: [PATCH v2] doc: Fix htmldocs build warnings of stallwarn.rst

[Leizhen (ThunderTown)]

On 2022/11/24 11:34, Leizhen (ThunderTown) wrote:
> 
> 
> On 2022/11/23 21:54, Bagas Sanjaya wrote:
>> On Wed, Nov 23, 2022 at 08:02:38PM +0800, Zhen Lei wrote:
>>> Documentation/RCU/stallwarn.rst:
>>> 401: WARNING: Literal block expected; none found.
>>> 428: WARNING: Literal block expected; none found.
>>> 445: WARNING: Literal block expected; none found.
>>> 459: WARNING: Literal block expected; none found.
>>> 468: WARNING: Literal block expected; none found.
>>>
>>> The literal block need to be indented, so add two spaces to each line.
>>
>> Indenting to match alignment of lists texts?
> 
> It's required by reStructuredText Markup Specification.
> 
> Indented Literal Blocks
> Indented literal blocks are indicated by indentation relative to the
> surrounding text (leading whitespace on each line). The literal block
> ends with the end of the indentation.
> 
> The surrounding text need to be indented, relative to the paragraphs
> above and below it and at the same level.
> 
>>
>>> Signed-off-by: Zhen Lei <thunder.leizhen@xxxxxxxxxx>
>>
>> You miss crediting linux-next list, so please add:
>>
>> Link: https://lore.kernel.org/linux-next/20221123163255.48653674@xxxxxxxxxxxxxxxx/
>> Fixes: 3d2788ba4573 ("doc: Document CONFIG_RCU_CPU_STALL_CPUTIME=y stall information")
>> Reported-by: Stephen Rothwell <sfr@xxxxxxxxxxxxxxxx>
> 
> OK, thanks.
> 
>>
>>> -The sampling period is shown as follows:
>>> -:<------------first timeout---------->:<-----second timeout----->:
>>> -:<--half timeout-->:<--half timeout-->:                          :
>>> -:                  :<--first period-->:                          :
>>> -:                  :<-----------second sampling period---------->:
>>> -:                  :                  :                          :
>>> -:          snapshot time point    1st-stall                  2nd-stall
>>> +The sampling period is shown as follows::
>>>  
>>> +  |<------------first timeout---------->|<-----second timeout----->|
>>> +  |<--half timeout-->|<--half timeout-->|                          |
>>> +  |                  |<--first period-->|                          |
>>> +  |                  |<-----------second sampling period---------->|
>>> +  |                  |                  |                          |
>>> +  |          snapshot time point    1st-stall                  2nd-stall
>>
>> The beginning pipe (|) on the last line of diagram above shouldn't be there
>> (axis label?).
> 
> OK, it might look better to delete it.
> 
> The text in literal block is treated as plain text.
> 
> 
>>
>>>  
>>>  The following describes four typical scenarios:
>>>  
>>> -1. A CPU looping with interrupts disabled.::
>>> +1. A CPU looping with interrupts disabled.
>>>  
>>> -   rcu:          hardirqs   softirqs   csw/system
>>> -   rcu:  number:        0          0            0
>>> -   rcu: cputime:        0          0            0   ==> 2500(ms)
>>> +   ::
>>> +
>>> +     rcu:          hardirqs   softirqs   csw/system
>>> +     rcu:  number:        0          0            0
>>> +     rcu: cputime:        0          0            0   ==> 2500(ms)
>>>  
>>>     Because interrupts have been disabled throughout the measurement
>>>     interval, there are no interrupts and no context switches.
>>> @@ -440,11 +442,11 @@ The following describes four typical scenarios:
>>>  
>>>     This is similar to the previous example, but with non-zero number of
>>>     and CPU time consumed by hard interrupts, along with non-zero CPU
>>> -   time consumed by in-kernel execution.::
>>> +   time consumed by in-kernel execution. ::
>>>  
>>> -   rcu:          hardirqs   softirqs   csw/system
>>> -   rcu:  number:      624          0            0
>>> -   rcu: cputime:       49          0         2446   ==> 2500(ms)
>>> +     rcu:          hardirqs   softirqs   csw/system
>>> +     rcu:  number:      624          0            0
>>> +     rcu: cputime:       49          0         2446   ==> 2500(ms)
>>>  
>>>     The fact that there are zero softirqs gives a hint that these were
>>>     disabled, perhaps via local_bh_disable().  It is of course possible
>>> @@ -454,20 +456,22 @@ The following describes four typical scenarios:
>>>  
>>>  3. A CPU looping with preemption disabled.
>>>  
>>> -   Here, only the number of context switches is zero.::
>>> +   Here, only the number of context switches is zero. ::
>>>  
>>> -   rcu:          hardirqs   softirqs   csw/system
>>> -   rcu:  number:      624         45            0
>>> -   rcu: cputime:       69          1         2425   ==> 2500(ms)
>>> +     rcu:          hardirqs   softirqs   csw/system
>>> +     rcu:  number:      624         45            0
>>> +     rcu: cputime:       69          1         2425   ==> 2500(ms)
>>>  
>>>     This situation hints that the stalled CPU was looping with preemption
>>>     disabled.
>>>  
>>> -4. No looping, but massive hard and soft interrupts.::
>>> +4. No looping, but massive hard and soft interrupts.
>>> +
>>> +   ::
>>>  
>>> -   rcu:          hardirqs   softirqs   csw/system
>>> -   rcu:  number:       xx         xx            0
>>> -   rcu: cputime:       xx         xx            0   ==> 2500(ms)
>>> +     rcu:          hardirqs   softirqs   csw/system
>>> +     rcu:  number:       xx         xx            0
>>> +     rcu: cputime:       xx         xx            0   ==> 2500(ms)
>>>  
>>>     Here, the number and CPU time of hard interrupts are all non-zero,
>>>     but the number of context switches and the in-kernel CPU time consumed
>>>
>>
>> Because paragraphs below the snippets directly refers to them,just use colon: 
> 
> This makes the style inconsistent when viewed on the web page. So I decided not
> to change it.
> 
> Take your advice and the end result will be as follows: (1 and 4 followed by a
> colon, 2 and 3 followed by a dot)
> 
> 1. A CPU looping with interrupts disabled:
> 2. A CPU looping with bottom halves disabled.
> 3. A CPU looping with preemption disabled.
> 4. No looping, but massive hard and soft interrupts:

Oh, I accept the suggestions for items 2 and 3.

> 
>>
>> ---- >8 ----
>>
>> diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst
>> index f15b766d39b8d9..4f6b91be03cfe0 100644
>> --- a/Documentation/RCU/stallwarn.rst
>> +++ b/Documentation/RCU/stallwarn.rst
>> @@ -423,9 +423,7 @@ The sampling period is shown as follows::
>>  
>>  The following describes four typical scenarios:
>>  
>> -1. A CPU looping with interrupts disabled.
>> -
>> -   ::
>> +1. A CPU looping with interrupts disabled::
>>  
>>       rcu:          hardirqs   softirqs   csw/system
>>       rcu:  number:        0          0            0
>> @@ -442,7 +440,7 @@ The following describes four typical scenarios:
>>  
>>     This is similar to the previous example, but with non-zero number of
>>     and CPU time consumed by hard interrupts, along with non-zero CPU
>> -   time consumed by in-kernel execution. ::
>> +   time consumed by in-kernel execution::
>>  
>>       rcu:          hardirqs   softirqs   csw/system
>>       rcu:  number:      624          0            0
>> @@ -456,7 +454,7 @@ The following describes four typical scenarios:
>>  
>>  3. A CPU looping with preemption disabled.
>>  
>> -   Here, only the number of context switches is zero. ::
>> +   Here, only the number of context switches is zero::
>>  
>>       rcu:          hardirqs   softirqs   csw/system
>>       rcu:  number:      624         45            0
>> @@ -465,9 +463,7 @@ The following describes four typical scenarios:
>>     This situation hints that the stalled CPU was looping with preemption
>>     disabled.
>>  
>> -4. No looping, but massive hard and soft interrupts.
>> -
>> -   ::
>> +4. No looping, but massive hard and soft interrupts::
>>  
>>       rcu:          hardirqs   softirqs   csw/system
>>       rcu:  number:       xx         xx            0
>>
>> Thanks.
>>
> 

-- 
Regards,
  Zhen Lei