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

[Kevin Wolf <kwolf@redhat.com>]

Am 08.09.2020 um 14:03 hat Laszlo Ersek geschrieben:
> 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 ;))

I think this is actually a more general problem with the way we generate
the documentation. For example, the "Background jobs" documentation ends
up under "Block Devices" just because qapi-schema.json includes
block-core.json before job.json and block-core.json includes job.json to
be able to access some types.

Maybe we should always look for the least nested include directive to
figure out where the documentation should be placed. Then things
directly referenced by qapi-schema.json would always be on the top
level.

Possibly we would then want to remove some includes from
qapi-schema.json and include them only from some other file to group
documentation sections that actually make sense to be grouped together.

Kevin