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

[Leizhen (ThunderTown)]

On 2022/11/28 12:08, Bagas Sanjaya wrote:
> On Thu, Nov 24, 2022 at 02:22:03PM +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.
>>
> 
> What about following patch description below instead?
> 
> ```
> When merging rcu tree for linux-next, Stephen Rothwell reported htmldocs
> warnings:
> 
> <warnings>...
> 
> These are due to unindented literal blocks. Indent them to fix these
> warnings.
> ```

That's great. Thanks.

> 
>> diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst
>> index c1e92dfef40d501..ca7b7cd806a16c9 100644
>> --- a/Documentation/RCU/stallwarn.rst
>> +++ b/Documentation/RCU/stallwarn.rst
>> @@ -398,9 +398,9 @@ In kernels built with CONFIG_RCU_CPU_STALL_CPUTIME=y or booted with
>>  rcupdate.rcu_cpu_stall_cputime=1, the following additional information
>>  is supplied with each RCU CPU stall warning::
>>  
>> -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)
>>  
> 
> OK.
>  
>> -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
>>  
> 
> OK.
> 
>>  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)
> 
> OK.
> 
>>     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)
> 
> OK.
> 
>>  
>>  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)
> 
> OK.
> 
>>  
>>     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.
>> +
>> +   ::
> 
> No, no that way. For consistency, the item sentence should also be end with
> double colon marker:

If you open Documentation/output/RCU/stallwarn.html on a web page, you'll find
that my current change is correct. Indented paragraphs are displayed in smaller
fonts. I want the following four sentences to end with a dot. Subparagraphs that
are subordinate to them are additionally indented. So there's no need to use
colons to emphasize it.

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.

> 
> ---- >8 ----
> 
> diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst
> index ca7b7cd806a16c..056127ef2b8e7e 100644
> --- a/Documentation/RCU/stallwarn.rst
> +++ b/Documentation/RCU/stallwarn.rst
> @@ -465,9 +465,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