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