Re: [PATCH] Documentation: RCU: use code blocks with autogenerated line (was: Re: linux-next: build warning after merge of the rcu tree)

[Paul E. McKenney]

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