[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v5 00/20] Convert QAPI doc comments to generate rST instead o
Re: [PATCH v5 00/20] Convert QAPI doc comments to generate rST instead of texinfo
Fri, 04 Sep 2020 16:34:06 +0200
Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux)
Peter Maydell <email@example.com> writes:
> On Mon, 10 Aug 2020 at 20:50, Peter Maydell <firstname.lastname@example.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)
# Tell sphinx of the dependency
> 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
As you can see, the module names are file names relative to the main
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
diff --git a/scripts/qapi/types.py b/scripts/qapi/types.py
index 3ad33af4ee..cec89e199c 100644
@@ -274,6 +274,10 @@ class QAPISchemaGenTypeVisitor(QAPISchemaModularCVisitor):
# gen_object() is recursive, ensure it doesn't visit the empty type
+ def visit_module(self, name):
+ print('### %r' % name)
def _gen_type_cleanup(self, name):
- Re: [PATCH v5 00/20] Convert QAPI doc comments to generate rST instead of texinfo,
Markus Armbruster <=