On Wed, Mar 5, 2025 at 5:10 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@redhat.com> writes: > > > Instead of using the info object for the doc block as a whole (which > > always points to the very first line of the block), update the info > > pointer for each call to ensure_untagged_section when the existing > > section is otherwise empty. This way, Sphinx error information will > > match precisely to where the text actually starts. > > > > For example, this patch will move the info pointer for the "Hello!" > > untagged section ... > > > >> ## <-- from here ... > >> # Hello! <-- ... to here. > >> ## > > > > Signed-off-by: John Snow <js...@redhat.com> > > This patch would be easier to accept with a test case where it improves > the error location. I tried to construct one quickly, but failed. Can > you help? > > Possible substitute: point to a patch later in this series where things > become worse without this patch. Maybe we can use the "if build_docs" section of the qapi schema testing to run things through Sphinx and harvest the error messages for negative cases...? I gotta sit down and figure out how. In the meantime, if I unapply my series, then edit block-core to look like this: ## # @SnapshotInfo: # # rST syntax error: *ahh! # (Lines 13-17, error is on line 16) Building, I get this error: /home/jsnow/src/qemu/docs/../qapi/block-core.json:14: WARNING: Inline emphasis start-string without end-string. [docutils] /home/jsnow/src/qemu/docs/../storage-daemon/qapi/../../qapi/block-core.json:14: WARNING: Inline emphasis start-string without end-string. [docutils] Mmm, nope. Not quite. If I re-push my series and try again with the same edit ... /home/jsnow/src/qemu/docs/../qapi/block-core.json:14: WARNING: Inline emphasis start-string without end-string. [docutils] /home/jsnow/src/qemu/docs/../storage-daemon/qapi/../../qapi/block-core.json:14: WARNING: Inline emphasis start-string without end-string. [docutils] /home/jsnow/src/qemu/docs/../qapi/block-core.json:16: WARNING: Inline emphasis start-string without end-string. [docutils] The two inclusions from the old qapidoc are still wrong, but the inclusion through the new transmogrifier is correct. (I'm going to be honest with you, I don't know why the error location didn't change at all for the old qapidoc. I think one of the many error location bugs I fixed when writing the new transmogrifier that just never got applied to the old system...) If I undo this fix but keep the rest of my series, I get these errors: /home/jsnow/src/qemu/docs/../qapi/block-core.json:14: WARNING: Inline emphasis start-string without end-string. [docutils] /home/jsnow/src/qemu/docs/../storage-daemon/qapi/../../qapi/block-core.json:14: WARNING: Inline emphasis start-string without end-string. [docutils] /home/jsnow/src/qemu/docs/../qapi/block-core.json:13: WARNING: Inline emphasis start-string without end-string. [docutils] Two are from the old qapidoc, one is from the new one. They're all wrong. --js
