Peter Maydell <peter.mayd...@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 :) [...]
