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
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
On 11/7/22 18:48, Akira Yokosawa wrote:
> 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.
>
I think only rcubarrier.rst have explicit references to line numbers.
Also, besides manual line counting, readers seeing rst sources can deduce
where actually the lines are from explanation of the snippet. Of course
they can make htmldocs and seeing the output if they want.
> 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.
>
There's also :emphasize-lines: option to highlight selected line numbers.
Thanks.
--
An old man doll... just what I always wanted! - Clara
[Dropping most CCs]
On Tue, 8 Nov 2022 09:29:01 +0700, Bagas Sanjaya wrote:
> On 11/7/22 18:48, Akira Yokosawa wrote:
>> 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.
>>
>
> I think only rcubarrier.rst have explicit references to line numbers.
Oh, I find such references in (not limited to):
- Documentation/RCU/Design/Requirements/Requirements.rst
- Documentation/RCU/Design/Data-Structures/Data-Structures.rst
>
> Also, besides manual line counting, readers seeing rst sources can deduce
> where actually the lines are from explanation of the snippet.
Maybe, maybe not... Deducing may take time.
> Of course
> they can make htmldocs and seeing the output if they want.
There can be situations where you can't afford such luxuries.
Remember there is a note in Documentation/doc-guide/sphinx.rst
which reads:
Please don't go overboard with reStructuredText markup. Keep it simple.
For the most part the documentation should be plain text with just enough
consistency in formatting that it can be converted to other formats.
My interpretation of above:
.rst sources should be kept as close to plain-text which can be
easily understood in dumb terminals, as far as possible.
>
>> 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.
>>
>
> There's also :emphasize-lines: option to highlight selected line numbers.
But that option doesn't do any highlighting while viewing .rst files
as plain-text. What am I missing?
Thanks, Akira
>
> Thanks.
>
On 11/8/22 21:53, Akira Yokosawa wrote:
>> I think only rcubarrier.rst have explicit references to line numbers.
>
> Oh, I find such references in (not limited to):
>
> - Documentation/RCU/Design/Requirements/Requirements.rst
> - Documentation/RCU/Design/Data-Structures/Data-Structures.rst
>
Ah, I don't see these above!
> Remember there is a note in Documentation/doc-guide/sphinx.rst
> which reads:
>
> Please don't go overboard with reStructuredText markup. Keep it simple.
> For the most part the documentation should be plain text with just enough
> consistency in formatting that it can be converted to other formats.
>
> My interpretation of above:
>
> .rst sources should be kept as close to plain-text which can be
> easily understood in dumb terminals, as far as possible.
>
Ah! I always forget that. I'm leaning towards *abusing* the markup,
though.
Thanks for the reminder.
--
An old man doll... just what I always wanted! - Clara