Peter Maydell <peter.mayd...@linaro.org> writes: > This series switches all our QAPI doc comments over from texinfo > format to rST. It then removes all the texinfo machinery, because > this was the last user of texinfo. > > I think I have now resolved all of Markus' issues raised in his > review of v5, and IMHO this is ready to commit. If there are still > things needing fixing, it would be nice if we were able to commit > patches 1-5, which are the ones which add the new indent-sensitive > code to the QAPI parser. That would put a stop to the steady trickle > of doc-comment changes which break the new rules... > > Also available as a git branch at > https://git.linaro.org/people/peter.maydell/qemu-arm.git sphinx-conversions-v6 > > 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 chosen 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. > > Changes from v5: > * rebased (in particular, updated to meson build system) > * new patch 1 fixes indent issues that hit master since v5 > * new patch 2 makes block-latency-histogram-set's use of Example > sections match everybody else's, instead of special casing it > in the parser > * the .gitignore got pruned after meson conversion so we only > need to change git.orderfile now > * slightly reordered patches to bring the parser.py indent change nearer > the start of the series in the hopes of being able to get at least > that much of the series into master > * we now tell Sphinx about all the json files for dependency info, > so editing a json file correctly rebuilds the docs > * added a test case for the bad-de-indent parser error > * Adopted the various Python scripting suggestions from Markus > * We don't insist on section headings being the only thing in their > doc comment block any more (the existing "must be first line" > requirement is sufficient) > * added a test case for doc-generation that does a compare of > the sphinx plain-text builder output against a reference file > * Added the Python source files for Sphinx extensions (including > the QAPI source files) to the dependency lists for the manuals, > so that changes made to them correctly trigger a docs rebuild > * qemu-ga-ref.rst and qemu-qmp-ref.rst now have a TODO note about > making the manual licensing more visible to readers > * fixed bug in reported file/line info for some errors in rST > in doc comments when using Sphinx 1.6 > * don't insist on section headers being in their own freeform doc > comment block; they're (after commit dcdc07a97cbe) always the > first line in the comment block, so just handle the possibility > of having text after that. > > There are a few things I have left out of this initial series: > > * unlike the texinfo, there is no generation of index entries > or an index in the HTML docs > * although there are HTML anchors on all the command/object/etc > headings, they are not stable but just serial-number based > tags like '#qapidoc-35', so not suitable for trying to link > to from other parts of the docs > > My view is that we can add niceties like this later; the series > already seems big enough to me.
Queued, thanks!
