On Thu, Dec 19, 2024 at 7:31 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@redhat.com> writes: > > > based-on: > https://patchew.org/QEMU/20241213011307.2942030-1-js...@redhat.com/ > > > > Hi! > > > > This series is a very, very barebones implementation for the new QAPI > > doc generator. It does not have many features that I presented on at KVM > > Forum; the point of this patch set is instead to present a stripped down > > basis for ongoing work so we can discuss on-list with full context of > > the code available to do so. > > > > The documentation this series generates is *not suitable* for replacing > > the current document generator, it has a few glaring omissions - on > > purpose - those features have been factored out intentionally so they > > can be reviewed with fuller context and more careful review. > > > > What this series does: > > > > - Adds the new "Transmogrifier" rST generator to qapidoc.py, which > > generates an in-memory rST document using qapi-domain directives. > > - Adds a test document that showcases this new transmogrifier. > > Note to other reviewers: transmogrifier output is > docs/manual/qapi/index.html. > > > What this series very notably does not do (yet): > > > > - "ifcond" data for anything other than top-level entities is not > > considered or rendered. This means "if" statements for features and > > members are entirely absent. > > > > - The inliner is not present at all. This series renders only > > documentation exactly as it is exists in the source files. > > This item is not even a regression. > No; but the version of this series as sent also does not add "The members of ..." stubs, which would be a regression. I didn't necessarily intend for this to be merged as-is; more of a "part one, with additional tricky elements that require more careful thought isolated into separate patches for later". where "later" means "in v2" or "as a follow-up series as we stage things in a development branch before final submission for inclusion to origin/master" or whatever the actual mechanism is. I don't have a strong vision there, really; I just wanted to nail down the basics out in the open even if that was just between you (Markus) and I and we have a gentleman's agreement that it looks tentatively OK. > > > - *branches* are themselves not considered at all; they're skipped > > entirely for now. They will be included alongside the inliner in > > either a subsequent series or a followup to this series. > > > > - Undocumented members and return statements are not autogenerated. > > The current doc generator auto-generates missing member documentation > ("Not documented"). It doesn't auto-generate missing returns > documentation. I explored auto-generating them, but shelved my work to > not interfere with yours. > > > - Pseudofeatures (Things like allow-oob) are not generated as documented > > features. > > What exactly are "pseudofeatures"? > What I've named things like allow-oob that aren't features, but ought to be documented. We may well decide to promote them to real-deal special features, or maybe not. My work-in-progress branch currently just adds "dummy" features to document them. We can discuss this later alongside the patch that implements this. > > > - Documentation culling: all entities are documented whether or not > > they're relevant to the wire format. > > Also not a regression. > > > My goal in doing it this way is to save the "fancy" features for later > > so we can focus on reviewing and tightening up the core functionality of > > the transmogrifier. Once we're on steadier ground, I will re-add the > > fanciful features while adjusting the qapi-domain mechanisms. Once > > everything looks "roughly right, give or take some minor nits", I will > > switch back to the qapi-domain series itself for review before we merge > > everything together. > > Makes sense to me. > > [...] > > > docs/index.rst | 1 + > > docs/qapi/index.rst | 53 ++++++ > > docs/sphinx/qapidoc.py | 419 ++++++++++++++++++++++++++++++++++++++--- > > scripts/qapi/parser.py | 97 +++++++--- > > scripts/qapi/source.py | 4 +- > > 5 files changed, 524 insertions(+), 50 deletions(-) > > create mode 100644 docs/qapi/index.rst > > The changes to the QAPI generator core (scripts/qapi/) are small, and > spread over just four patches: > > qapi/source: allow multi-line QAPISourceInfo advancing > qapi/schema: add __repr__ to QAPIDoc.Section > qapi: expand tags to all doc sections > qapi/parser: adjust info location for doc body section > >
