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

[Markus Armbruster]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Mon, 10 Aug 2020 at 20:50, Peter Maydell <peter.maydell@linaro.org> wrote:
>> This series switches all our QAPI doc comments over from
>> texinfo format to rST. It then removes all the texinfo
>> machinery, because this was the last user of texinfo.
>>
>> This is largely just a rebase of patchset v4 to current master.

It needs another rebase now, for the Meson build system.

>> There are a few things I have left out of this initial series:
>
> I realized there is something I forgot to add to this "left out" list:
>
> Sphinx needs to know what all the input files which go into
> a document are, as it builds up dependencies to tell it whether
> to rebuild the output or not. The docs/sphinx/qapidoc.py
> plugin adds such a dependency on the file that the .rst
> docs reference (eg qapi/qapi-schema.json)

In QAPIDocDirective.run():

        # Tell sphinx of the dependency
        env.note_dependency(os.path.abspath(qapifile))


>                                           but it does not
> have a mechanism for adding dependencies when that .json
> file uses an 'include' to pull in other .json files.
>
> 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.

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'

As you can see, the module names are file names relative to the main
module's directory.

Module None is for built-ins.

Unfortunately, your qapidoc.py bypasses the regular schema.visit() just
like old doc.py does, and for the same reason: it wants to iterate over
doc comments, not definitions.  Doc comments were bolted on later, and
it still shows.

I figure the clean solution is making schema.visit() pass doc comments
just like it passes entities.  Gets rid of the need to bypass
schema.visit().  Requires surgery to QAPISchema and QAPISchemaParser.

A quick hack: use a trivial QAPISchemaVisitor just to collect the
modules.

Questions?



diff --git a/scripts/qapi/types.py b/scripts/qapi/types.py
index 3ad33af4ee..cec89e199c 100644
--- a/scripts/qapi/types.py
+++ b/scripts/qapi/types.py
@@ -274,6 +274,10 @@ class QAPISchemaGenTypeVisitor(QAPISchemaModularCVisitor):
         # gen_object() is recursive, ensure it doesn't visit the empty type
         objects_seen.add(schema.the_empty_object_type.name)
 
+    def visit_module(self, name):
+        print('### %r' % name)
+        super().visit_module(name)
+
     def _gen_type_cleanup(self, name):
         self._genh.add(gen_type_cleanup_decl(name))
         self._genc.add(gen_type_cleanup(name))