Re: [PATCH] Documentation: sched: Add a new sched-util-clamp.rst

[Qais Yousef <qyousef@layalina.io>]

On 11/14/22 15:55, Bagas Sanjaya wrote:
> On Sun, Nov 13, 2022 at 03:26:29PM +0000, Qais Yousef wrote:
> > Thanks! I have the below fixup patch that addresses these. It made me realize
> > my html output could look better. It's cosmetic; so won't post a new version
> > till some feedback is provided first.
> > 
> > 
> > Cheers
> > 
> > --
> > Qais Yousef
> > 
> > 
> > --->8---
> > 
> > diff --git a/Documentation/scheduler/index.rst b/Documentation/scheduler/index.rst
> > index b430d856056a..f12d0d06de3a 100644
> > --- a/Documentation/scheduler/index.rst
> > +++ b/Documentation/scheduler/index.rst
> > @@ -15,6 +15,7 @@ Linux Scheduler
> >      sched-capacity
> >      sched-energy
> >      schedutil
> > +    sched-util-clamp
> >      sched-nice-design
> >      sched-rt-group
> >      sched-stats
> > diff --git a/Documentation/scheduler/sched-util-clamp.rst b/Documentation/scheduler/sched-util-clamp.rst
> > index e75b69767afb..728ffa364fc7 100644
> > --- a/Documentation/scheduler/sched-util-clamp.rst
> > +++ b/Documentation/scheduler/sched-util-clamp.rst
> > @@ -169,24 +169,27 @@ could change with implementation details.
> >  2.1  BUCKETS:
> >  -------------
> >  
> > +.. code-block:: c
> > +
> >                             [struct rq]
> >  
> > -(bottom)                                                    (top)
> > +  (bottom)                                                    (top)
> >  
> > -  0                                                          1024
> > -  |                                                           |
> > -  +-----------+-----------+-----------+----   ----+-----------+
> > -  |  Bucket 0 |  Bucket 1 |  Bucket 2 |    ...    |  Bucket N |
> > -  +-----------+-----------+-----------+----   ----+-----------+
> > -     :           :                                   :
> > -     +- p0       +- p3                               +- p4
> > -     :                                               :
> > -     +- p1                                           +- p5
> > -     :
> > -     +- p2
> > +    0                                                          1024
> > +    |                                                           |
> > +    +-----------+-----------+-----------+----   ----+-----------+
> > +    |  Bucket 0 |  Bucket 1 |  Bucket 2 |    ...    |  Bucket N |
> > +    +-----------+-----------+-----------+----   ----+-----------+
> > +       :           :                                   :
> > +       +- p0       +- p3                               +- p4
> > +       :                                               :
> > +       +- p1                                           +- p5
> > +       :
> > +       +- p2
> 
> The code block above is diagram, isn't it? Thus specifying language for
> syntax highlighting (in this case ``c``) isn't appropriate.

I could do with a helping hand here actually. I am a text only person but
trying to follow the new rst docs; but I don't have a clue to be honest.

I did try to find the right directive, but I couldn't find it. What should be
specified for this diagram?

> 
> >  
> >  
> > -DISCLAMER:
> > +.. note::
> > +  DISCLAMER:
> >     The diagram above is an illustration rather than a true depiction of the
> >     internal data structure.
> 
> The DISCLAIMER line above isn't needed, since note block should do the
> job.

Okay.

> 
> >  
> > @@ -200,6 +203,8 @@ The rq has a bucket for each uclamp_id: [UCLAMP_MIN, UCLAMP_MAX].
> >  The range of each bucket is 1024/N. For example for the default value of 5 we
> >  will have 5 buckets, each of which will cover the following range:
> >  
> > +.. code-block:: c
> > +
> 
> Again, why ``c`` syntax highlighting?

This is a C code snippet. What would be better to use? I think I was getting
errors if I don't specify something. But again; I was touching my way around in
the dark here trying to figure it out.

> Otherwise no new warnings. Thanks for fixing this up.
> 
> However, in the future, for documentation patches you should always Cc:
> linux-doc list. Adding it to Cc list now.

Indeed. Maybe I went into auto-mode and didn't use get_maintainer proper.
Apologies.


Thanks!

--
Qais Yousef