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

[Peter Maydell]

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.
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.

thanks
-- PMM