[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH] libqos/qgraph: format qgraph comments for sphinx documentati
Emanuele Giuseppe Esposito
Re: [PATCH] libqos/qgraph: format qgraph comments for sphinx documentation
Wed, 24 Feb 2021 11:59:00 +0100
Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.7.0
On 24/02/2021 11:49, Paolo Bonzini wrote:
On 24/02/21 11:18, Emanuele Giuseppe Esposito wrote:
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.