Re: [PATCH v2 61/62] docs: enable qapidoc transmogrifier for QEMU QMP Reference

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> We are not enabling the transmogrifier for QSD or QGA yet because we
> don't (yet) have a way to create separate indices, and all of the
> definitions will bleed together, which isn't so nice.
>
> For now, QMP is better than nothing at all!
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  docs/interop/qemu-qmp-ref.rst | 1 +
>  qapi/qapi-schema.json         | 2 ++
>  2 files changed, 3 insertions(+)
>
> diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst
> index f94614a0b2f..e95eeac45e2 100644
> --- a/docs/interop/qemu-qmp-ref.rst
> +++ b/docs/interop/qemu-qmp-ref.rst
> @@ -7,3 +7,4 @@ QEMU QMP Reference Manual
>     :depth: 3
>  
>  .. qapi-doc:: qapi/qapi-schema.json
> +   :transmogrify:
> diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json
> index 2877aff73d0..4475e81cc3e 100644
> --- a/qapi/qapi-schema.json
> +++ b/qapi/qapi-schema.json
> @@ -5,6 +5,8 @@
>  #
>  # This document describes all commands currently supported by QMP.
>  #
> +# For locating a particular item, please see the `qapi-index`.
> +#

```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.

>  # Most of the time their usage is exactly the same as in the user
>  # Monitor, this means that any other document which also describe
>  # commands (the manpage, QEMU's manual, etc) can and should be