Message ID | 20200206173040.17337-1-peter.maydell@linaro.org (mailing list archive) |
---|---|
Headers | show |
Series | Convert QAPI doc comments to generate rST instead of texinfo | expand |
On Thu, 6 Feb 2020 at 17:30, Peter Maydell <peter.maydell@linaro.org> wrote: > This series switches all our QAPI doc comments over from > texinfo format to rST. Oops, this fails 'make check' because I forgot to run it (not thinking of docs changes as being stuff that affects test) and there are a couple of golden-master files that need updating. I have some minor changes that I'll put in v2 which correct that: * a new patch "tests/qapi/doc-good.json: Clean up markup" which removes some oddities of the old markup that we don't want to support, tightening up the tested doc comments: * in a single list the bullet types must all match * lists must have leading and following blank lines * indentation is important * the '|' example syntax is going to go away entirely, so stop testing it * patches "scripts/qapi: Move doc-comment whitespace stripping to doc.py" and "scripts/qapi/parser.py: improve doc comment indent handling" both make minor whitespace changes that require updates to the tests/qapi-schema/doc-good.out reference * "scripts/qapi: Remove texinfo generation support" now removes the no-longer-used tests/qapi-schema/doc-good.texi I won't send v2 until this has had some review, though. If you want a git branch with the pending-for-v2 fixups it's at: https://git.linaro.org/people/peter.maydell/qemu-arm.git sphinx-conversions thanks -- PMM
Patchew URL: https://patchew.org/QEMU/20200206173040.17337-1-peter.maydell@linaro.org/ Hi, This series failed the docker-mingw@fedora build test. Please find the testing commands and their output below. If you have Docker installed, you can probably reproduce it locally. === TEST SCRIPT BEGIN === #! /bin/bash export ARCH=x86_64 make docker-image-fedora V=1 NETWORK=1 time make docker-test-mingw@fedora J=14 NETWORK=1 === TEST SCRIPT END === GEN docs/index.html CC crypto/aes.o No filename or title make: *** [/tmp/qemu-test/src/rules.mak:392: docs/interop/qemu-qmp-ref.7] Error 255 make: *** Waiting for unfinished jobs.... Traceback (most recent call last): File "./tests/docker/docker.py", line 664, in <module> --- raise CalledProcessError(retcode, cmd) subprocess.CalledProcessError: Command '['sudo', '-n', 'docker', 'run', '--label', 'com.qemu.instance.uuid=62059c3553b64eb384aee0a720c4473b', '-u', '1003', '--security-opt', 'seccomp=unconfined', '--rm', '-e', 'TARGET_LIST=', '-e', 'EXTRA_CONFIGURE_OPTS=', '-e', 'V=', '-e', 'J=14', '-e', 'DEBUG=', '-e', 'SHOW_ENV=', '-e', 'CCACHE_DIR=/var/tmp/ccache', '-v', '/home/patchew2/.cache/qemu-docker-ccache:/var/tmp/ccache:z', '-v', '/var/tmp/patchew-tester-tmp-_3tt9kgf/src/docker-src.2020-02-06-14.51.13.6510:/var/tmp/qemu:z,ro', 'qemu:fedora', '/var/tmp/qemu/run', 'test-mingw']' returned non-zero exit status 2. filter=--filter=label=com.qemu.instance.uuid=62059c3553b64eb384aee0a720c4473b make[1]: *** [docker-run] Error 1 make[1]: Leaving directory `/var/tmp/patchew-tester-tmp-_3tt9kgf/src' make: *** [docker-run-test-mingw@fedora] Error 2 real 2m2.836s user 0m8.762s The full log is available at http://patchew.org/logs/20200206173040.17337-1-peter.maydell@linaro.org/testing.docker-mingw@fedora/?type=message. --- Email generated automatically by Patchew [https://patchew.org/]. Please send your feedback to patchew-devel@redhat.com
Patchew URL: https://patchew.org/QEMU/20200206173040.17337-1-peter.maydell@linaro.org/ Hi, This series failed the docker-quick@centos7 build test. Please find the testing commands and their output below. If you have Docker installed, you can probably reproduce it locally. === TEST SCRIPT BEGIN === #!/bin/bash make docker-image-centos7 V=1 NETWORK=1 time make docker-test-quick@centos7 SHOW_ENV=1 J=14 NETWORK=1 === TEST SCRIPT END === CC tests/test-qapi-commands.o CC tests/test-string-input-visitor.o CC tests/test-string-output-visitor.o doc-good FAIL --- /tmp/qemu-test/src/tests/qapi-schema/doc-good.out +++ @@ -1,199 +0,0 @@ --- +++ @@ -0,0 +1 @@ +doc-good.json:104:1: unexpected de-indent make: *** [check-tests/qapi-schema/frontend] Error 1 make: *** Waiting for unfinished jobs.... CC tests/test-qmp-event.o Traceback (most recent call last): --- raise CalledProcessError(retcode, cmd) subprocess.CalledProcessError: Command '['sudo', '-n', 'docker', 'run', '--label', 'com.qemu.instance.uuid=ac8e8dbf593c42e385721554759cb252', '-u', '1003', '--security-opt', 'seccomp=unconfined', '--rm', '-e', 'TARGET_LIST=', '-e', 'EXTRA_CONFIGURE_OPTS=', '-e', 'V=', '-e', 'J=14', '-e', 'DEBUG=', '-e', 'SHOW_ENV=1', '-e', 'CCACHE_DIR=/var/tmp/ccache', '-v', '/home/patchew2/.cache/qemu-docker-ccache:/var/tmp/ccache:z', '-v', '/var/tmp/patchew-tester-tmp-y9h_kw4r/src/docker-src.2020-02-06-14.53.51.11537:/var/tmp/qemu:z,ro', 'qemu:centos7', '/var/tmp/qemu/run', 'test-quick']' returned non-zero exit status 2. filter=--filter=label=com.qemu.instance.uuid=ac8e8dbf593c42e385721554759cb252 make[1]: *** [docker-run] Error 1 make[1]: Leaving directory `/var/tmp/patchew-tester-tmp-y9h_kw4r/src' make: *** [docker-run-test-quick@centos7] Error 2 real 2m17.651s user 0m7.653s The full log is available at http://patchew.org/logs/20200206173040.17337-1-peter.maydell@linaro.org/testing.docker-quick@centos7/?type=message. --- Email generated automatically by Patchew [https://patchew.org/]. Please send your feedback to patchew-devel@redhat.com
Peter Maydell <peter.maydell@linaro.org> writes: > This series switches all our QAPI doc comments over from > texinfo format to rST. > > The basic approach is somewhat similar to how we deal with kerneldoc > and hxtool: we have a custom Sphinx extension which is passed a > filename which is the json file it should run the QAPI parser over and > generate documentation for. Unlike 'kerneldoc' but somewhat like > hxtool, I have chosed to generate documentation by generating a tree > of docutils nodes, rather than by generating rST source that is then > fed to the rST parser to generate docutils nodes. Individual lumps of > doc comment go to the rST parser, but the structured parts we render > directly. This makes it easier to get the structure and heading level > nesting correct. > > Rather than trying to exactly handle all the existing comments I have > opted (as Markus suggested) to tweak them where this seemed more > sensible than contorting the rST generator to deal with > weirdnesses. The principal changes are: > * whitespace is now significant, and multiline definitions must have > their second and subsequent lines indented to match the first line > * general rST format markup is permitted, not just the small set of > markup the old texinfo generator handled. For most things (notably > bulleted and itemized lists) the old format is the same as rST was. > * Specific things that might trip people up: > - instead of *bold* and _italic_ rST has **bold** and *italic* Actually, qapi-code-gen.txt documents and doc.py implements *strong* and _emphasis_. Texinfo commonly renders them as bold and italic when the output format supports that. rST has **strong** and *emphasis*. Your series adjusts emphasis markup for rST [PATCH 18]. Since it doesn't touch strong markup, strong silently becomes emphasis. I guess that's okay, perhaps even an improvement, but double-checking the actual uses of this markup wouldn't hurt. > - lists need a preceding and following blank line > - a lone literal '*' will need to be backslash-escaped to > avoid a rST syntax error > * the old leading '|' for example (literal text) blocks is replaced > by the standard rST '::' literal block. > * headings and subheadings must now be in a freeform documentation > comment of their own Can we simply use rST instead? See my review of PATCH 18. > * we support arbitrary levels of sub- and sub-sub-heading, not just a > main and sub-heading like the old texinfo generator > * as a special case, @foo is retained and is equivalent to ``foo`` Apart from these remarks, your changes look sensible to me right now. I hope they'll still look that way when I'm done reviewing :) [...]
On Fri, 7 Feb 2020 at 17:00, Markus Armbruster <armbru@redhat.com> wrote: > > Peter Maydell <peter.maydell@linaro.org> writes: > > > This series switches all our QAPI doc comments over from > > texinfo format to rST. > > > > The basic approach is somewhat similar to how we deal with kerneldoc > > and hxtool: we have a custom Sphinx extension which is passed a > > filename which is the json file it should run the QAPI parser over and > > generate documentation for. Unlike 'kerneldoc' but somewhat like > > hxtool, I have chosed to generate documentation by generating a tree > > of docutils nodes, rather than by generating rST source that is then > > fed to the rST parser to generate docutils nodes. Individual lumps of > > doc comment go to the rST parser, but the structured parts we render > > directly. This makes it easier to get the structure and heading level > > nesting correct. > > > > Rather than trying to exactly handle all the existing comments I have > > opted (as Markus suggested) to tweak them where this seemed more > > sensible than contorting the rST generator to deal with > > weirdnesses. The principal changes are: > > * whitespace is now significant, and multiline definitions must have > > their second and subsequent lines indented to match the first line > > * general rST format markup is permitted, not just the small set of > > markup the old texinfo generator handled. For most things (notably > > bulleted and itemized lists) the old format is the same as rST was. > > * Specific things that might trip people up: > > - instead of *bold* and _italic_ rST has **bold** and *italic* > > Actually, qapi-code-gen.txt documents and doc.py implements *strong* and > _emphasis_. Texinfo commonly renders them as bold and italic when the > output format supports that. rST has **strong** and *emphasis*. > > Your series adjusts emphasis markup for rST [PATCH 18]. Since it > doesn't touch strong markup, strong silently becomes emphasis. I guess > that's okay, perhaps even an improvement, but double-checking the actual > uses of this markup wouldn't hurt. Yeah, that would be a good plan. git grep '\*[^*]*\*' qapi/*.json (and eyeball-filtering out the false hits) shows just one use: qapi/introspect.json:# Note: the QAPI schema is also used to help define *internal* I can put a patch on the end which converts that to **internal** once the rST generator is in use. > > - lists need a preceding and following blank line > > - a lone literal '*' will need to be backslash-escaped to > > avoid a rST syntax error > > * the old leading '|' for example (literal text) blocks is replaced > > by the standard rST '::' literal block. > > * headings and subheadings must now be in a freeform documentation > > comment of their own > > Can we simply use rST instead? See my review of PATCH 18. No, we can't (see my reply to that review). In theory you could have the heading syntax be a rST heading, but that is not feasible to recognise in the Python script[*] and it gives the impression that it is just an inline rST heading, not something that's more complicated and structured. [*] You'd need to manually re-implement the weird thing rST does where practically any kind of underlining is valid and it figures out which one means which depth by looking at the usage through the whole document. You'd have to do bizarre stuff like running through the entire set of doc comments once doing no output but just looking at heading underline characters to guess which one is which depth, and then once you'd figured that out you could do it all over again actually generating the doc. thanks -- PMM
Peter Maydell <peter.maydell@linaro.org> writes: > On Fri, 7 Feb 2020 at 17:00, Markus Armbruster <armbru@redhat.com> wrote: >> >> Peter Maydell <peter.maydell@linaro.org> writes: >> >> > This series switches all our QAPI doc comments over from >> > texinfo format to rST. >> > >> > The basic approach is somewhat similar to how we deal with kerneldoc >> > and hxtool: we have a custom Sphinx extension which is passed a >> > filename which is the json file it should run the QAPI parser over and >> > generate documentation for. Unlike 'kerneldoc' but somewhat like >> > hxtool, I have chosed to generate documentation by generating a tree >> > of docutils nodes, rather than by generating rST source that is then >> > fed to the rST parser to generate docutils nodes. Individual lumps of >> > doc comment go to the rST parser, but the structured parts we render >> > directly. This makes it easier to get the structure and heading level >> > nesting correct. >> > >> > Rather than trying to exactly handle all the existing comments I have >> > opted (as Markus suggested) to tweak them where this seemed more >> > sensible than contorting the rST generator to deal with >> > weirdnesses. The principal changes are: >> > * whitespace is now significant, and multiline definitions must have >> > their second and subsequent lines indented to match the first line >> > * general rST format markup is permitted, not just the small set of >> > markup the old texinfo generator handled. For most things (notably >> > bulleted and itemized lists) the old format is the same as rST was. >> > * Specific things that might trip people up: >> > - instead of *bold* and _italic_ rST has **bold** and *italic* >> >> Actually, qapi-code-gen.txt documents and doc.py implements *strong* and >> _emphasis_. Texinfo commonly renders them as bold and italic when the >> output format supports that. rST has **strong** and *emphasis*. >> >> Your series adjusts emphasis markup for rST [PATCH 18]. Since it >> doesn't touch strong markup, strong silently becomes emphasis. I guess >> that's okay, perhaps even an improvement, but double-checking the actual >> uses of this markup wouldn't hurt. > > Yeah, that would be a good plan. > git grep '\*[^*]*\*' qapi/*.json > (and eyeball-filtering out the false hits) shows just one use: > > qapi/introspect.json:# Note: the QAPI schema is also used to help > define *internal* > > I can put a patch on the end which converts that to **internal** > once the rST generator is in use. I wrote that one, and I think changing it from strong to emphasis is an improvement. Let's point to it in the commit message, and call it a day. >> > - lists need a preceding and following blank line >> > - a lone literal '*' will need to be backslash-escaped to >> > avoid a rST syntax error >> > * the old leading '|' for example (literal text) blocks is replaced >> > by the standard rST '::' literal block. >> > * headings and subheadings must now be in a freeform documentation >> > comment of their own >> >> Can we simply use rST instead? See my review of PATCH 18. > > No, we can't (see my reply to that review). In theory you could have > the heading syntax be a rST heading, but that is not feasible to > recognise in the Python script[*] and it gives the impression that > it is just an inline rST heading, not something that's more complicated > and structured. > > [*] You'd need to manually re-implement the weird thing rST does > where practically any kind of underlining is valid and it figures > out which one means which depth by looking at the usage through > the whole document. You'd have to do bizarre stuff like running > through the entire set of doc comments once doing no output but > just looking at heading underline characters to guess which one > is which depth, and then once you'd figured that out you could > do it all over again actually generating the doc. I understand the difficulty of parsing rST (Paolo called it "the Perl of markup languages" for a reason). What I don't yet understand is (1) why we need to recognize the document structure of doc comments, and (2) why we can do that by recognizing '=' markup, but ignore the native rST document structure markup.
On Sat, 8 Feb 2020 at 14:16, Markus Armbruster <armbru@redhat.com> wrote: > I understand the difficulty of parsing rST (Paolo called it "the Perl of > markup languages" for a reason). What I don't yet understand is (1) why > we need to recognize the document structure of doc comments, and (2) why > we can do that by recognizing '=' markup, but ignore the native rST > document structure markup. I think we're completely at cross purposes here, so there's something I've not managed to communicate clearly. We don't need to recognize the document structure of doc comments, indeed my implementation does not -- it just throws a doc comment at the rST parser to handle. We *do* need to recognize the structure *of the document* (ie that it does have a thing with a heading "Block devices" that contains another thing with a heading "Background jobs" that in turn contains documentation for JobType, JobStatus....) so that when we're building up our tree of docutils node objects we know when we need to create a new 'section' node and give it a title 'Block devices' and which of the various section nodes in the tree should have all the nodes that make up the documentation of 'JobType' added to it. In order to achieve this separation (don't care about document structure inside lumps of rST, but do want to know what the overall section/subsection structure of the document is), this patchset pulls the identification of the document structure (heading/subheadings) completely out of being something you might find in the middle of a doc comment, and makes them their own special kind of markup: ## # = This is a heading ## (In my head I find I'm thinking of this as "not actually a doc comment", which is probably where some of my lack of clarity is coming from, since syntactically speaking and from the point of view of qapi/parser.py that is a sort of doc comment.) I suppose that there's an argument that the identification of headings and subheadings should really be done in qapi/parser.py, so that instead of vis = QAPISchemaGenRSTVisitor(self) vis.visit_begin(schema) for doc in schema.docs: if doc.symbol: vis.symbol(doc, schema.lookup_entity(doc.symbol)) else: vis.freeform(doc) you would have something more like vis = QAPISchemaGenRSTVisitor(self) vis.visit_begin(schema) for doc in schema.docs: if doc.symbol: vis.symbol(doc, schema.lookup_entity(doc.symbol)) else if doc.is_section_header: vis.start_new_section(doc) else: vis.freeform(doc) (with the identification of headers and pulling out of what level of nesting this header is and what its text is done in parser.py) thanks -- PMM
On Thursday, February 6, 2020, Peter Maydell <peter.maydell@linaro.org> wrote: > > > This series switches all our QAPI doc > > > comments over from > > texinfo format to rST. > > Regardeless of the outcome of the discussions over this series, I just want to say that I support it as a potential user of the document (there is no "Supported-by:" mark or similar, so this is all I can do). Also, as a general participant in QEMU community, I seems to me this is a significant step in shaping up QEMU documentation. Best regards, Aleksandar > >