[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 17/16] docs/devel/qapi-code-gen: Describe some doc markup pit
From: |
Markus Armbruster |
Subject: |
Re: [PATCH 17/16] docs/devel/qapi-code-gen: Describe some doc markup pitfalls |
Date: |
Thu, 27 Apr 2023 14:36:16 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/28.2 (gnu/linux) |
Juan Quintela <quintela@redhat.com> writes:
> Markus Armbruster <armbru@redhat.com> wrote:
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>
> Reviewed-by: Juan Quintela <quintela@redhat.com>
Thanks!
>> ---
>> docs/devel/qapi-code-gen.rst | 53 ++++++++++++++++++++++++++++++++++++
>> 1 file changed, 53 insertions(+)
>>
>> diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
>> index d81aac7a19..14983b074c 100644
>> --- a/docs/devel/qapi-code-gen.rst
>> +++ b/docs/devel/qapi-code-gen.rst
[...]
>> +When you change documentation comments, please check the generated
>> +documentation comes out as intended!
>
> What is the easiest way to see the code generated for some subsystem,
> say migration.json and find the problems and undocumented stuff?
>
> I am expecting something in the lines of:
> - you run this command
> - and look at this file
Make sure building documentation is enabled, run "make", and look at
bld-clang/docs/manual/interop/qemu-qmp-ref.html. Documentation for
qapi/migration.json is in section "Migration" (because
qapi/migration.json starts with a "# = Migration" heading).
Sphinx can produce a number of formats. Our build system only does HTML
and manual pages. I like to also produce plain text for easy diffing.
I grab the sphinx-build invocation from "make V=1" and replace "-b html"
by "-b text".
- Re: [PATCH v2 03/16] qapi: Fix misspelled references, (continued)
- [PATCH v2 05/16] qapi/block-core: Clean up after removal of dirty bitmap @status, Markus Armbruster, 2023/04/25
- [PATCH v2 01/16] qga/qapi-schema: Tidy up documentation of guest-fsfreeze-status, Markus Armbruster, 2023/04/25
- [PATCH v2 15/16] qapi: Format since information the conventional way: (since X.Y), Markus Armbruster, 2023/04/25
- [PATCH v2 16/16] qapi storage-daemon/qapi: Fix documentation section structure, Markus Armbruster, 2023/04/25
- [PATCH v2 12/16] qapi: Fix argument documentation markup, Markus Armbruster, 2023/04/25
- [PATCH v2 06/16] qapi: @foo should be used to reference, not ``foo``, Markus Armbruster, 2023/04/25
- [PATCH 17/16] docs/devel/qapi-code-gen: Describe some doc markup pitfalls, Markus Armbruster, 2023/04/27
- [PATCH 17/16] docs/devel/qapi-code-gen: Describe some doc markup pitfalls, Markus Armbruster, 2023/04/27