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

[Paolo Bonzini <pbonzini@redhat.com>]

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.

> + * DOC: Qtest Driver Framework

Is this needed since you have the heading already in qgraph.rst?

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

> + * 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.

Thanks!

Paolo