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

[Emanuele Giuseppe Esposito]

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