Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <af3ec8bf-310e-69ea-9d32-f7aec740b306@gmail.com>
Date:   Mon, 7 Nov 2022 20:48:23 +0900
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.2.2
To:     Bagas Sanjaya <bagasdotme@gmail.com>
Cc:     corbet@lwn.net, frederic@kernel.org, jiangshanlai@gmail.com,
        joel@joelfernandes.org, josh@joshtriplett.org,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        linux-next@vger.kernel.org, mathieu.desnoyers@efficios.com,
        paulmck@kernel.org, quic_neeraju@quicinc.com, rcu@vger.kernel.org,
        rostedt@goodmis.org, sfr@canb.auug.org.au,
        Akira Yokosawa <akiyks@gmail.com>
References: <Y2jWAR1QESe3OrhH@debian.me>
Subject: [PATCH] Documentation: RCU: use code blocks with autogenerated line
 (was: Re: linux-next: build warning after merge of the rcu tree)
Content-Language: en-US
From:   Akira Yokosawa <akiyks@gmail.com>
In-Reply-To: <Y2jWAR1QESe3OrhH@debian.me>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

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.

          Thanks, Akira