lkml.org 
[lkml]   [2022]   [Nov]   [7]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH] Documentation: RCU: use code blocks with autogenerated line (was: Re: linux-next: build warning after merge of the rcu tree)
On Mon, Nov 07, 2022 at 08:48:23PM +0900, Akira Yokosawa wrote:
> Hi Bagas,
>
> On Mon, 7 Nov 2022 16:55:13 +0700, Bagas Sanjaya wrote:
> > On Sun, Nov 06, 2022 at 09:02:12PM -0800, Paul E. McKenney wrote:
> >> On Mon, Nov 07, 2022 at 02:26:41PM +1100, Stephen Rothwell wrote:
> >> > Hi all,
> >> >
> >> > After merging the rcu tree, today's linux-next build (htmldocs)
> >> > produced this warning:
> >> >
> >> > Documentation/RCU/rcubarrier.rst:205: WARNING: Literal block ends without a blank line; unexpected unindent.
> >> >
> >> > Introduced by commit
> >> >
> >> > 21c2e3909721 ("doc: Update rcubarrier.rst")
> >>
> >> Huh. I guess that numbered code samples are not supposed to have more
> >> than nine lines? Ah well, easy to fix by going back to left-justified
> >> numbers. I was wondering about that!
> >>
> >
> > I think the proper fix is just let Sphinx generates line number:
>
> That might be true if all you care about were the generated documents,
> but we need to pay attention to readers of .rst files as plain-text.
>
> There are a bunch of references to line numbers in RCU documents.
> If explicit line numbers are removed from snippets, such readers need
> to count the lines by themselves, which doesn't sound reasonable to me.
>
> If you can put labels to referenced lines within code snippets, auto
> generation of line numbers might work, but as far as I know, Sphinx
> doesn't provide such a nice feature.
>
> Of course, you can prove me wrong.

I will give Bagas a few days to prove Akira wrong. ;-)

Either way, thank you both for looking into this!

Thanx, Paul

\
 
 \ /
  Last update: 2022-11-07 18:52    [W:0.446 / U:0.020 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site