Re: [PATCH v5 09/20] docs/sphinx: Add new qapi-doc Sphinx extension

[Markus Armbruster <armbru@redhat.com>]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Mon, 21 Sep 2020 at 19:06, Peter Maydell <peter.maydell@linaro.org> wrote:
>> (I've just noticed that with Sphinx 1.6, which we still have
>> to support, the file/line info isn't passed through, so you get:
>>
>> Warning, treated as error:
>> /home/petmay01/linaro/qemu-from-laptop/qemu/docs/interop/qemu-qmp-ref.rst:7:Bullet
>> list ends without a blank line; unexpected unindent.
>>
>> The plugin has code borrowed from kerneldoc.py which is
>> *supposed* to handle the older API Sphinx 1.6 used, but it
>> looks like it's broken. I'll have a look and see if it
>> is fixable, but possibly we may have to live with people
>> developing on old distros getting suboptimal errors.)
>
> Tracked down the cause of this -- it turns out that if you
> feed nested_parse_with_titles() bogus rST then in some
> cases it will detect the error with a line number that's
> one off the end of the input text, eg on the 2 lines:
> 0: * a bulleted list
> 1: a misindented line
>
> there's a syntax error here where line 1 is misindented,
> but at least Sphinx 1.6 wants to attribute the error to a
> nonexistent line 2, which then doesn't match in the
> input-lines-to-source-info mapping for the fragment
> and so gets reported for the next level out (the .rst file).
> It just happened that the syntax error I used to test the
> file/line reporting this time around was one of this kind.

Lucky!

> I assume Sphinx 3 either gets the line attribution more
> accurate or is not using the same mechanism for finding
> the input line in the source mapping.
>
> The fix is just to always add a blank line at the end of
> every .rst fragment we hand to the Sphinx parser, which
> doesn't affect the generated output and does sidestep this
> issue.

Sounds good, as long as it has a comment explaining why we need this.