This is RFC quality and mostly meant for Markus to review, but if you're curious about what we're up to, you're welcome to nose around :)
It's a hackish application of enforcing a strict source section ordering in QAPIDoc and the accompanying patches that mend the source to respect that order. The point of the series is to, ultimately, make it easier to "inject" auto-generated documentation by enforcing a specific order to sections so that it is easier to insert documentation that is missing or can be implied from the source. A secondary goal is to more closely align the source documentation ordering with what gets rendered on the HTML documentation. I am sending it to the list in this RFC state mostly to illustrate what each specific imposition requires in terms of source doc changes, and as a refresher for the specific restrictions I want to make to facilitate the inliner feature. I am not neccessarily married to any specific technique/implementation for each specific restriction, but if it looks broadly OK to you (Markus), I can work on any requested polish or corollary cleanups. If you'd like to see a different approach, that's fine too. We may wish to discuss the ability to add notes/addendums to sections and what syntax would support that. I had originally thought I'd work on the @oob project, but quickly remembered that my approach to that feature required yet-another place where we inject a doc section, and decided it would be best if I solved "where do we inject this autogenerated section?" once and for all, hence, you are getting this series first. John Snow (8): qapi: differentiate "intro" and "details" sections qapi: prohibit 'details' sections between tagged sections qapi: add "Details:" disambiguation marker qapi: detect potentially semantically ambiguous intro paragraphs qapi: re-order QAPI doc block sections qapi: enforce doc block section ordering qapi: re-order 'since' sections to always be last qapi: enforce strict positioning for "Since:" section docs/interop/firmware.json | 4 +- docs/interop/vhost-user.json | 3 +- docs/sphinx/qapidoc.py | 2 +- qapi/accelerator.json | 12 +-- qapi/acpi.json | 8 +- qapi/block-core.json | 183 ++++++++++++++++---------------- qapi/block-export.json | 20 ++-- qapi/block.json | 48 ++++----- qapi/char.json | 36 +++---- qapi/control.json | 14 +-- qapi/dump.json | 16 +-- qapi/machine-s390x.json | 16 +-- qapi/machine.json | 144 +++++++++++++------------ qapi/migration.json | 102 ++++++++++-------- qapi/misc-arm.json | 6 +- qapi/misc-i386.json | 40 ++++--- qapi/misc.json | 68 ++++++------ qapi/net.json | 42 ++++---- qapi/pci.json | 4 +- qapi/qdev.json | 12 +-- qapi/qom.json | 34 +++--- qapi/replay.json | 16 +-- qapi/rocker.json | 16 +-- qapi/run-state.json | 66 +++++++----- qapi/tpm.json | 12 +-- qapi/trace.json | 8 +- qapi/transaction.json | 4 +- qapi/ui.json | 76 +++++++------ qapi/vfio.json | 4 +- qapi/virtio.json | 46 ++++---- qapi/yank.json | 2 +- scripts/qapi/parser.py | 121 ++++++++++++++++++--- tests/qapi-schema/doc-good.json | 12 +-- tests/qapi-schema/doc-good.out | 10 +- tests/qapi-schema/doc-good.txt | 18 ++-- 35 files changed, 695 insertions(+), 530 deletions(-) -- 2.53.0
