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

[Peter Maydell]

On Fri, 4 Sep 2020 at 15:34, Markus Armbruster <armbru@redhat.com> wrote:
> Peter Maydell <peter.maydell@linaro.org> writes:
> > I'm not sure whether the scripts/qapi code supports telling
> > a consumer of the parsed info about this -- is it sufficient
> > for QAPISchemaGenRSTVisitor to implement the 'visit_include'
> > method, find the path to the included .qapi file from the
> > arguments and call Sphinx's env.notedependency(), or do we
> > need to do something more complicated to get the list of
> > all the included .qapi files ?
>
> Visitors can implement visit_include() to see include directives.
> QAPISchemaModularCVisitor does, to generate #include that mirror the
> source schema.  This is not what your want.

Why not? Surely "see include directives" is exactly what I want?
Any time the QAPI parser opens a file that's different from the
initial one we want to know about it.

> You want visit_module().  The appended hack makes qapi-gen.py spit out
> the modules when it generates types, e.g.:
>
>     $ python3 -B scripts/qapi-gen.py -o scratch 
> tests/qapi-schema/qapi-schema-test.json
>     ### None
>     ### 'qapi-schema-test.json'
>     ### 'include/sub-module.json'
>     ### 'sub-sub-module.json'

What's a "module" here ? Does this still produce output if the
top level .json file includes a sub-json file that doesn't actually
have any contents ? (We still want to generate the dependency
then, so we update the docs if the included file is edited to
add content.)

thanks
-- PMM