Re: [PATCH] libqos/qgraph: format qgraph comments for sphinx documentation

[Emanuele Giuseppe Esposito <eesposit@redhat.com>]

On 24/02/2021 11:49, Paolo Bonzini wrote:
> On 24/02/21 11:18, Emanuele Giuseppe Esposito wrote:
>>     qtest
>> +   qgraph
> 
> It may make sense to add instead a "toctree" directive in qtest.rst.  I 
> haven't checked what the result looks like, though.

Current result is

- QTest Device Emulation Testing Framework
- Qtest Driver Framework

but I agree, maybe with an internal toctree in qtest.rst it will be 
clearer. I'll try.

> 
>> + * DOC: Qtest Driver Framework
> 
> Is this needed since you have the heading already in qgraph.rst?

No, sorry I was experimenting and looking at qtest.rst
I forgot to remove it

> 
> (Also, the whole section could move to qgraph.rst.  This is what was 
> done with qom.rst for example).

Ok makes sense.

> 
>> + * More specifically:
>> + *
>> + * .. code::
>> + *
>> + *   x86_64/pc -->contains--> other_node <--consumes-- my_driver
>> + *                                                         |
> 
> You can end a paragraph with "::", and the following block will 
> automatically become monospaced.
> 
> Also "-->contains-->" has an extra ">" sign.
> 
>> + * ``"-netdev something -device my_node,addr=04.0 -device other"``
> 
> Maybe the quotes can be removed since you have monospaced text.
> 
> The main issue with the text overall is that it was written before 
> having experience with developing QGraph drivers and interfaces.  It's 
> already a good thing to have it in the manual, so the smallest possible 
> change (as you did in this patch) is already an improvement.
> 
> However, it would also be nice to replace the examples with something 
> more "real world", based on the code in tests/qtest.

I will try to use better examples and post v2, thank you for the feedback.

Emanuele
> 
> Thanks!
> 
> Paolo
>