Re: [PATCH 00/29] Convert QAPI doc comments to generate rST instead of texinfo

[Markus Armbruster]

Peter Maydell <address@hidden> 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 :)

[...]