Re: [PATCH 08/11] docs/qapi-domain: add namespaced index support

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> Generate an index-per-namespace for the QAPI domain. Due to a limitation
> with Sphinx's architecture, these indices must be defined during setup
> time and cannot be dynamically created on-demand when a namespace
> directive is encountered.
>
> Owing to that limitation, add a configuration value to conf.py that
> specifies which QAPI namespaces we'll generate indices for.
>
> Indices will be named after their namespace, e.g. the "QMP" namespace
> will generate to "qapi-qmp-index.html" and can be referenced using
> `qapi-qmp-index`.
>
> Signed-off-by: John Snow <jsnow@redhat.com>

I'm going to state my understanding of a few things.  Please correct
misunderstandings, if any.

Before this patch, the QAPI domain creates a single index, and it's
named "QAPI Index".

It has "everything".

This patch adds one index per namespace.  There are none, yet.  The next
patch will add namespace "QMP", and the last patch adds "QGA" and "QSD".

Each of these indexes will have exactly the stuff in that namespace.

The QAPI Index continues to have everything.

The patch adding namespace "QMP" replaces the QEMU QMP Reference
Manual's link to the QAPI Index by a link to the QMP reference (the QAPI
index is no longer linked from anywhere).  At that time, their contents
is still identical, but that stops when the last patch enables the
transmogrifier more widely, so the replacement is clearly necessary.

Since we put everything QAPI in a namespace, the QAPI index has no
entries that aren't also in a namespace's index.

Since QSD's schema is a subset of QMP's, everything in the QSD index and
also in the QMP index.

The QAPI index has everything...  does it link to QMP's copy or QSD's
copy?  I checked block-commit, and it appears to link to QMP's.