[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 1/4] docs: lift block-core.json rST header into parents
From: |
Markus Armbruster |
Subject: |
Re: [PATCH 1/4] docs: lift block-core.json rST header into parents |
Date: |
Wed, 09 Sep 2020 09:38:19 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) |
Kevin Wolf <kwolf@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 <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.
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?
- [PATCH 0/4] docs: add qemu-storage-daemon documentation, Stefan Hajnoczi, 2020/09/08
- [PATCH 1/4] docs: lift block-core.json rST header into parents, Stefan Hajnoczi, 2020/09/08
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Laszlo Ersek, 2020/09/08
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Kevin Wolf, 2020/09/08
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents,
Markus Armbruster <=
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Kevin Wolf, 2020/09/09
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Markus Armbruster, 2020/09/09
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Kevin Wolf, 2020/09/09
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Markus Armbruster, 2020/09/09
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Kevin Wolf, 2020/09/09
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Markus Armbruster, 2020/09/10
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Kevin Wolf, 2020/09/10
Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Kevin Wolf, 2020/09/09
[PATCH 2/4] docs: generate qemu-storage-daemon-qmp-ref(7) man page, Stefan Hajnoczi, 2020/09/08
[PATCH 3/4] docs: add qemu-storage-daemon(1) man page, Stefan Hajnoczi, 2020/09/08