Re: [PATCH 1/4] docs: lift block-core.json rST header into parents

[Kevin Wolf <kwolf@redhat.com>]

Am 08.09.2020 um 11:31 hat Stefan Hajnoczi geschrieben:
> block-core.json is included from several places. It has no way of
> knowing what header level (h1, h2, ...) is appropriate. Sphinx reports
> errors when it encounters an h2 header where it expects an h1 header.
> This issue prevents the next patch from generating documentation for
> qemu-storage-daemon QMP commands.
> 
> Move the header into parents so that the correct header level can be
> used. Note that transaction.json is not updated since it doesn't seem to
> need a header.
> 
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  docs/interop/firmware.json | 4 ++++
>  qapi/block-core.json       | 4 ----
>  qapi/block.json            | 1 +
>  3 files changed, 5 insertions(+), 4 deletions(-)

storage-daemon/qapi/qapi-schema.json needs an update, too. With the
series as it is, the block-core.json definitions don't get any headline
at all and look as if they were part of the previous section.

Maybe a nicer solution would be to keep the second-level heading where
it is, but to just add a first-level one to the storage daemon
qapi-schema.json. It makes sense to group block-core and block-export
together even without the system emulator part, so the top-level
section wouldn't be arbitrary either, but we would add a second
subsection soon.

Kevin