Message ID | 20200309154405.13548-3-peter.maydell@linaro.org |
---|---|
State | Superseded |
Headers | show |
Series | Convert QAPI doc comments to generate rST instead of texinfo | expand |
On 3/9/20 8:43 AM, Peter Maydell wrote: > Our current QAPI doc-comment markup allows section headers > (introduced with a leading '=' or '==') anywhere in any documentation > comment. This works for texinfo because the texi generator simply > prints a texinfo heading directive at that point in the output > stream. For rST generation, since we're assembling a tree of > docutils nodes, this is awkward because a new section implies > starting a new section node at the top level of the tree and > generating text into there. > > New section headings in the middle of the documentation of a command > or event would be pretty nonsensical, and in fact we only ever output > new headings using 'freeform' doc comment blocks whose only content > is the single line of the heading, with two exceptions, which are in > the introductory freeform-doc-block at the top of > qapi/qapi-schema.json. > > Split that doc-comment up so that the heading lines are in their own > doc-comment. This will allow us to tighten the specification to > insist that heading lines are always standalone, rather than > requiring the rST document generator to look at every line in a doc > comment block and handle headings in odd places. > > This change makes no difference to the generated texi. > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > --- > qapi/qapi-schema.json | 12 +++++++++--- > 1 file changed, 9 insertions(+), 3 deletions(-) Reviewed-by: Richard Henderson <richard.henderson@linaro.org> r~
Peter Maydell <peter.maydell@linaro.org> writes: > Our current QAPI doc-comment markup allows section headers > (introduced with a leading '=' or '==') anywhere in any documentation > comment. This works for texinfo because the texi generator simply > prints a texinfo heading directive at that point in the output > stream. For rST generation, since we're assembling a tree of > docutils nodes, this is awkward because a new section implies > starting a new section node at the top level of the tree and > generating text into there. > > New section headings in the middle of the documentation of a command > or event would be pretty nonsensical, and in fact we only ever output > new headings using 'freeform' doc comment blocks whose only content > is the single line of the heading, with two exceptions, which are in > the introductory freeform-doc-block at the top of > qapi/qapi-schema.json. > > Split that doc-comment up so that the heading lines are in their own > doc-comment. This will allow us to tighten the specification to > insist that heading lines are always standalone, rather than > requiring the rST document generator to look at every line in a doc > comment block and handle headings in odd places. > > This change makes no difference to the generated texi. > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > --- > qapi/qapi-schema.json | 12 +++++++++--- > 1 file changed, 9 insertions(+), 3 deletions(-) > > diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json > index fe980ce4370..ff5aea59451 100644 > --- a/qapi/qapi-schema.json > +++ b/qapi/qapi-schema.json > @@ -1,7 +1,9 @@ > # -*- Mode: Python -*- > ## > # = Introduction > -# > +## > + > +## > # This document describes all commands currently supported by QMP. > # > # Most of the time their usage is exactly the same as in the user Monitor, this > @@ -25,9 +27,13 @@ > # > # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for > # detailed information on the Server command and response formats. > -# > +## > + > +## > # = Stability Considerations > -# > +## > + > +## > # The current QMP command set (described in this file) may be useful for a > # number of use cases, however it's limited and several commands have bad > # defined semantics, specially with regard to command completion. The restriction you add is tolerable. But how does the doc generator behave when I get it wrong? The test case for getting it wrong is tests/qapi-schema/doc-bad-section.json. In current master (commit f57587c7d47b35b2d9b31def3a74d81bdb5475d7), $ scripts/qapi-gen.py tests/qapi-schema/doc-bad-section.json produces this qapi-doc.texi: @c AUTOMATICALLY GENERATED, DO NOT MODIFY @deftp {Enum} Enum @subsection Produces @strong{invalid} texinfo @b{Values:} @table @asis @item @code{one} The @emph{one} @{and only@} @item @code{two} Not documented @end table @code{two} is undocumented @end deftp This is invalid Texinfo: $ makeinfo qapi-doc.texi qapi-output-master/qapi-doc.texi:4: warning: entry for index `tp' outside of any node qapi-output-master/qapi-doc.texi:6: @subsection seen before @end deftp qapi-output-master/qapi-doc.texi:17: unmatched `@end deftp' [Exit 1 ] Ignore the warning, it's due to the harmlessly lazy test case. A developer who puts a section heading in the wrong place in the schema gets to divine his mistake from makeinfo's error messages. Not nice. After your rST conversion[*], ... Well, I tried to figure out how to build .html from tests/qapi-schema/doc-bad-section.json, but failed. Alright, use a heavier hammer: append that file to qapi-schema.json. Build succeeds, and produces a qemu-qmp-ref.7 that /usr/bin/man renders like this: Enum (Enum) == No good here Values one The _one_ {and only} two Not documented two is undocumented I consider this even worse than before. With my "[PATCH 1/2] qapi: Reject section markup in definition documentation", qapi-gen.py rejects it cleanly: tests/qapi-schema/doc-bad-section.json:5:1: unexpected '=' markup in definition documentation I believe it won't hinder your .rST conversion work. It might even help. Maybe only together with PATCH 2/2, but that's for you to decide. [*] Fetched from https://git.linaro.org/people/peter.maydell/qemu-arm.git sphinx-conversions
diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index fe980ce4370..ff5aea59451 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -1,7 +1,9 @@ # -*- Mode: Python -*- ## # = Introduction -# +## + +## # This document describes all commands currently supported by QMP. # # Most of the time their usage is exactly the same as in the user Monitor, this @@ -25,9 +27,13 @@ # # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for # detailed information on the Server command and response formats. -# +## + +## # = Stability Considerations -# +## + +## # The current QMP command set (described in this file) may be useful for a # number of use cases, however it's limited and several commands have bad # defined semantics, specially with regard to command completion.
Our current QAPI doc-comment markup allows section headers (introduced with a leading '=' or '==') anywhere in any documentation comment. This works for texinfo because the texi generator simply prints a texinfo heading directive at that point in the output stream. For rST generation, since we're assembling a tree of docutils nodes, this is awkward because a new section implies starting a new section node at the top level of the tree and generating text into there. New section headings in the middle of the documentation of a command or event would be pretty nonsensical, and in fact we only ever output new headings using 'freeform' doc comment blocks whose only content is the single line of the heading, with two exceptions, which are in the introductory freeform-doc-block at the top of qapi/qapi-schema.json. Split that doc-comment up so that the heading lines are in their own doc-comment. This will allow us to tighten the specification to insist that heading lines are always standalone, rather than requiring the rST document generator to look at every line in a doc comment block and handle headings in odd places. This change makes no difference to the generated texi. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> --- qapi/qapi-schema.json | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) -- 2.20.1