Re: [PATCH 17/16] docs/devel/qapi-code-gen: Describe some doc markup pitfalls

[Markus Armbruster <armbru@redhat.com>]

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".