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

[Laszlo Ersek <lersek@redhat.com>]

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 <stefanha@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' }
>