Kevin Wolf <kw...@redhat.com> writes: > 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 <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 ;)) > > 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.
The doc generator is stupid and greedy (which also makes it predictable): a module's documentation is emitted where it is first included. For full control of the order, have the main module include all sub-modules in the order you want. Alternatively, add just enough includes to get the order you want. > 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. I doubt implementing this feature would pay back the invested time. Manually controlling the order like I described above is not much of a burden, isn't it?