diff mbox series

doc: Fix htmldocs build warnings of stallwarn.rst

Message ID 20221123091246.1890-1-thunder.leizhen@huawei.com (mailing list archive)
State Superseded
Headers show
Series doc: Fix htmldocs build warnings of stallwarn.rst | expand

Commit Message

Leizhen (ThunderTown) Nov. 23, 2022, 9:12 a.m. UTC
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.

In addition, ':', which is used as a boundary in the literal block, is
replaced by '|'.

Signed-off-by: Zhen Lei <thunder.leizhen@huawei.com>
---
 Documentation/RCU/stallwarn.rst | 44 ++++++++++++++++-----------------
 1 file changed, 22 insertions(+), 22 deletions(-)

Comments

Leizhen (ThunderTown) Nov. 23, 2022, 11:41 a.m. UTC | #1
On 2022/11/23 17:12, 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.
> 
> In addition, ':', which is used as a boundary in the literal block, is
> replaced by '|'.
> 
> Signed-off-by: Zhen Lei <thunder.leizhen@huawei.com>
> ---
>  Documentation/RCU/stallwarn.rst | 44 ++++++++++++++++-----------------
>  1 file changed, 22 insertions(+), 22 deletions(-)
> 
> diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst
> index c1e92dfef40d501..0f6a58ebf5d7855 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)
>  
>  These statistics are collected during the sampling period. The values
>  in row "number:" are the number of hard interrupts, number of soft
> @@ -412,22 +412,22 @@ in milliseconds.  Because user-mode tasks normally do not cause RCU CPU
>  stalls, these tasks are typically kernel tasks, which is why only the
>  system CPU time are considered.
>  
> -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 following describes four typical scenarios:
>  
>  1. A CPU looping with interrupts disabled.::
>  

Wait, a space is need to be added before "::", otherwise, only one colon
will be removed from the output. And in this way, other paragraphs after
literal block are also displayed in red when using vim to edit stallwarn.rst.
So it would be better to use expanded form.

I will post v2.

> -   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.
> @@ -442,9 +442,9 @@ The following describes four typical scenarios:
>     and CPU time consumed by hard interrupts, along with non-zero CPU
>     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
> @@ -456,18 +456,18 @@ The following describes four typical scenarios:
>  
>     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.::
>  
> -   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
>
diff mbox series

Patch

diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst
index c1e92dfef40d501..0f6a58ebf5d7855 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)
 
 These statistics are collected during the sampling period. The values
 in row "number:" are the number of hard interrupts, number of soft
@@ -412,22 +412,22 @@  in milliseconds.  Because user-mode tasks normally do not cause RCU CPU
 stalls, these tasks are typically kernel tasks, which is why only the
 system CPU time are considered.
 
-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 following describes four typical scenarios:
 
 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.
@@ -442,9 +442,9 @@  The following describes four typical scenarios:
    and CPU time consumed by hard interrupts, along with non-zero CPU
    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
@@ -456,18 +456,18 @@  The following describes four typical scenarios:
 
    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.::
 
-   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