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

[Kevin Wolf <kwolf@redhat.com>]

Am 10.09.2020 um 07:18 hat Markus Armbruster geschrieben:
> Kevin Wolf <kwolf@redhat.com> writes:
> 
> > Am 09.09.2020 um 17:28 hat Markus Armbruster geschrieben:
> >> Kevin Wolf <kwolf@redhat.com> writes:
> >> 
> >> > Am 09.09.2020 um 14:10 hat Markus Armbruster geschrieben:
> >> >> Kevin Wolf <kwolf@redhat.com> writes:
> [...]
> >> >> > There are orders that I can't get this way.
> >> >> 
> >> >> You're right, ordering by first include is not completely general.
> >> >> 
> >> >> >                                             For example, if I want to
> >> >> > have "Block devices" documented before "Background jobs", there is no
> >> >> > way to add includes to actually get this order without having
> >> >> > "Background jobs" as a subsection in "Block devices".
> >> >> 
> >> >> "Background jobs" is job.json.
> >> >> 
> >> >> "Block devices" is block.json, which includes block-core.json, which
> >> >> includes job.json.
> >> >> 
> >> >> To be able to put "Block devices" first, you'd have to break the chain
> >> >> from block.json to job.json.  Which might even be an improvement:
> >> >> 
> >> >> $ wc -l qapi/*.json | awk '$1 >= 1000 { print }'
> >> >>   5527 qapi/block-core.json
> >> >>   1722 qapi/migration.json
> >> >>   1617 qapi/misc.json
> >> >>   1180 qapi/ui.json
> >> >>  17407 total
> >> >> 
> >> >> Could we split block-core.json into several cohesive parts?
> >> >
> >> > Possibly. However, while it would be an improvement generally speaking,
> >> > how does this change the specific problem? All of the smaller files will
> >> > be included by block.json (or whatever file provides the "Block devices"
> >> > chapter in the documentation) and at least one of them will still have
> >> > to include job.json.
> >> 
> >> Splitting block-core.json can help only if other modules then use less
> >> than all the parts.  In particular, as long as block.json includes the
> >> same stuff, it'll surely still include jobs.json.  Could it include
> >> less?
> >
> > Not if the documentation wants to have a single chapter for the block
> > layer instead of many small block related top-level chapters.
> >
> > Otherwise we could include some things directly from qapi-schema.json,
> > but obviously, that would still have to be after job.json for some
> > parts.
> 
> You're right.
> 
> Being unable to talk about something before you define it may not be all
> bad, though :)

Yes, as long as the resulting order is what we want anyway, this is not
a problem.

I'm just not sure if we will always be aware of the include structure
without tool support so that we would always declare the dependencies
first. Nobody checks the headlines in the documentation after making
schema changes.

Kevin