QAPI doc generator improvements (was: [PATCH v3 0/4] qapi/migration: Dedup migration parameter objects and fix tls-authz crash)

[Markus Armbruster]

Markus Armbruster <armbru@redhat.com> writes:

[...]

> I can see two useful QAPI generator features:
>
> * Improved handling of missing member documentation
>
>   Problem: many members lack documentation.  We silently generate
>   documentation like
>
>       name-of-member
>           Not documented
>
>   for them.
>
>   Possible improvement: make missing member documentation a hard error,
>   create a knob to suppress the error for a type.  Open question: how to
>   best document member documentation is incomplete.
>
> * Suppress documentation for internal-only definitions
>
>   Problem: generated documentation covers everything, even types that
>   aren't visible in QMP.  The irrelevant material is distracting and
>   possibly confusing for users, and may be bothersome to maintain for
>   developers.
>
>   Possible improvement: include only the types visible in QMP in
>   documentation, similar to how we do for query-qmp-schema.  Open
>   question: what level of documentation to require for internal-only
>   types.

I expored this one, and ran into a roadblock.

I wrote a bit of code to mark the stuff we want in QMP documentation:
commands, events, and the types they use, directly or indirectly.

I then hacked QAPISchemaGenRSTVisitor.symbol() to skip entities not
so marked.

Surprisingly, this does not work: the generated QEMU QMP Reference
Manual lacks stuff that is clearly in QMP.

I double-checked, and yes, the missing stuff does get marked.  WTF?!?

I dug some, and it looks like this is due to interference between the
QEMU QMP Reference Manual (generated from qapi/qapi-schema.json) and the
QEMU Storage Daemon QMP Reference Manual (generated from
storage-daemon/qapi/qapi-schema.json).

Both qapi-schema.json include submodules from qapi/., the former all of
them, the latter only some of them.  Yes, this is a bit of a hack.

sphinx-build runs the QAPI machinery separately for each of the two.
Somehow results from one run can leak into the other one.  For instance,
type HumanReadableText is marked in one run and not the other (correct),
but its documentation is generated in *neither* run.  I suspect this is
an artifact of incremental doc building magic.

I'm shelving the idea for now.