Peter Maydell <peter.mayd...@linaro.org> writes: > On Mon, 21 Sep 2020 at 19:06, Peter Maydell <peter.mayd...@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.
