John Snow <js...@redhat.com> writes: > This is just a test document that demonstrates the new qapi-domain doc > generator. Note that this test document uses a nesting depth of 2 for > the TOC unlike the existing QMP's reference nesting depth of 3. It's > arbitrary and can be changed to suit taste, it has nothing to do with > the new domain itself. > > Signed-off-by: John Snow <js...@redhat.com> > --- > docs/index.rst | 1 + > docs/qapi/index.rst | 53 +++++++++++++++++++++++++++++++++++++++++++++ > 2 files changed, 54 insertions(+) > create mode 100644 docs/qapi/index.rst > > diff --git a/docs/index.rst b/docs/index.rst > index 5665de85cab..4364f9f1618 100644 > --- a/docs/index.rst > +++ b/docs/index.rst > @@ -21,3 +21,4 @@ Welcome to QEMU's documentation! > specs/index > devel/index > glossary > + qapi/index > diff --git a/docs/qapi/index.rst b/docs/qapi/index.rst > new file mode 100644 > index 00000000000..e40dce09119 > --- /dev/null > +++ b/docs/qapi/index.rst > @@ -0,0 +1,53 @@ > +######################## > +QAPI Transmogrifier Test > +######################## > + > +This is a test render of the QEMU QMP reference manual using the new > +"transmogrifier" generator in qapidoc.py in conjunction with the > +qapi-domain.py sphinx extension. > + > +Some notable features: > + > + * Every QAPI definition visible below is available to be > + cross-referenced from anywhere else in the Sphinx docs; for example > + ```blockdev-add``` will render to `blockdev-add`. > + > + * There are type-specific cross-referencing roles available for > + alternates, commands, events, enums, structs, unions and modules. for > + example, ``:qapi:cmd:`block-dirty-bitmap-add``` resolves to > + :qapi:cmd:`block-dirty-bitmap-add`, and only works for commands. The > + roles available are ``cmd``, ``alt``, ``event``, ``enum``, > + ``struct``, ``union``, and ``mod``; with two meta-roles available: > + ``obj`` for absolutely any QAPI definition, and ``type`` for > + everything except commands, events, and modules. > + > + * There is a new `qapi-index` page which can be linked to with > + ```qapi-index```. There, you can browse a list of all QAPI > + definitions by type or alphabetically.
```qapi-index``` becomes a link in HTML. The link takes me to an index page. Two observations: * The index page appears not to be linked from the navigation thingie on the left. Searching for "QAPI Index" there doesn't find it, either. * The index is structured into sections titled Alternates, Commands | Enums, Events, Modules, Objects, A, ... Z. As I scrolled down quickly, the transition from Objects to A confused me briefly: I didn't immediately understand that A, ... Z contains the union of everything above sorted into letter buckets. > + > + * QAPI definitions are also added to the existing `genindex` page. > + > + * All member/argument/return types are now cross-references to that > + type's definition. `chardev-add` is a good example. > + > + * This work-in-progress version does not perform any inlining. > + > + * This work-in-progress version actually also ignores branches entirely > + right now! > + > + * This version currently does not "prune" unnecessary docs. > + > + * This version does not add undocumented members or return values. > + > + * This version does not handle ifcond for anything other than top-level > + entity definitions. > + > + * This version renders sections in precisely the order they appear in > + source, even if that winds up looking silly. > + > + > +.. contents:: > + :depth: 2 > + > +.. qapi-doc:: qapi/qapi-schema.json > + :transmogrify:
