| Message ID | 20250305034610.960147-55-jsnow@redhat.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | docs: Add new QAPI transmogrifier | expand |
John Snow <jsnow@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 <jsnow@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:
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 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:
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 <jsnow@redhat.com> --- docs/index.rst | 1 + docs/qapi/index.rst | 53 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 docs/qapi/index.rst