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: