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

[Bagas Sanjaya]

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?

> 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>

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

>  
>  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: 

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

-- 
An old man doll... just what I always wanted! - Clara

Attachment: signature.asc
Description: PGP signature