Hi Stefan,
On 09/08/20 11:31, Stefan Hajnoczi wrote:
> 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 <stefa...@redhat.com>
> ---
> docs/interop/firmware.json | 4 ++++
> qapi/block-core.json | 4 ----
> qapi/block.json | 1 +
> 3 files changed, 5 insertions(+), 4 deletions(-)
>
> diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json
> index 989f10b626..48af327f98 100644
> --- a/docs/interop/firmware.json
> +++ b/docs/interop/firmware.json
> @@ -15,6 +15,10 @@
> ##
>
> { 'include' : 'machine.json' }
> +
> +##
> +# == Block devices
> +##
> { 'include' : 'block-core.json' }
>
> ##
I think "docs/interop/firmware.json" deserves the same treatment as
"transaction.json".
It's been a long time since I last looked at a rendered view of
"docs/interop/firmware.json", but it only includes "block-core.json" so
it can refer to some block-related types (@BlockdevDriver seems like the
main, or only, one).
I wouldn't expect the rendered view of "firmware.json" to have a section
header saying "Block devices".
I think it should be fine to drop this hunk (and my CC along with it ;))
Thanks!
Laszlo
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index 55b58ba892..e986341997 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -1,10 +1,6 @@
> # -*- Mode: Python -*-
> # vim: filetype=python
>
> -##
> -# == Block core (VM unrelated)
> -##
> -
> { 'include': 'common.json' }
> { 'include': 'crypto.json' }
> { 'include': 'job.json' }
> diff --git a/qapi/block.json b/qapi/block.json
> index c54a393cf3..473b294a3b 100644
> --- a/qapi/block.json
> +++ b/qapi/block.json
> @@ -3,6 +3,7 @@
>
> ##
> # = Block devices
> +# == Block core (VM unrelated)
> ##
>
> { 'include': 'block-core.json' }
>
