Re: [PATCH v5 00/20] Convert QAPI doc comments to generate rST instead of texinfo

[Peter Maydell]

On Fri, 4 Sep 2020 at 16:54, Markus Armbruster <armbru@redhat.com> wrote:
> Initially, the include directive was just that: include another file's
> contents right here.
>
> Back in 2018, we switched from generating monolithic code to generating
> modular code.  What does that mean?
>
> Instead of generating the kitchen sink into a single qapi-types.c, we
> split out the stuff generated for each FOO.json included by
> qapi-schema.json into qapi-types-FOO.c.
>
> Same for qapi-types.h, but with #include stitching that mirrors the
> schema's include directives.  So, if FOO.json includes SUB.json, then
> qapi-types-FOO.h will include qapi-types-SUB.h.
>
> Same for qapi-{commands,events,visit}.{c,h}.
>
> The qapi-schema.json (rather: the file you pass to qapi-gen.py) is the
> main module.
>
> The .json it includes are the sub-modules.
>
> visit_module() lets you see the modules.
>
> visit_include() lets you see the includes.  The same module can be
> included multiple times.  Having to filter that out would be annoying.

I don't think you'd need to filter it out for this use case -- I
assume Sphinx would just ignore the unnecessary extra dependency
information. But if visit_module() does what we want and you
recommend it I'll look at that.

thanks
-- PMM