[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Emanuele Giuseppe Esposito
Subject: Re: [PATCH] libqos/qgraph: format qgraph comments for sphinx documentation
Date: Thu, 25 Feb 2021 09:22:42 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.7.0

On 24/02/2021 11:59, Emanuele Giuseppe Esposito wrote:

On 24/02/2021 11:49, Paolo Bonzini wrote:
On 24/02/21 11:18, Emanuele Giuseppe Esposito wrote:
+   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.

After trying, I think that simply adding a toctree in qtest.rst is not the prettiest solution. The end result will be something like

Qtest driver framework (title)
        - qgraph (link to qgraph.rst)
QTest is a device emulation testing framework... [qtest.rst content]

The qgraph link will be also visible in docs/index and docs/devel/index

What about this:

diff --git a/docs/devel/qgraph.rst b/docs/devel/qgraph.rst
index 9349c45af8..62a45cbcbf 100644
--- a/docs/devel/qgraph.rst
+++ b/docs/devel/qgraph.rst
@@ -1,5 +1,261 @@
+.. _qgraph:
 Qtest Driver Framework


Add anchor in graph.rst

 .. kernel-doc:: tests/qtest/libqos/qgraph.h
diff --git a/docs/devel/qtest.rst b/docs/devel/qtest.rst
index 97c5a75626..b7201456b6 100644
--- a/docs/devel/qtest.rst
+++ b/docs/devel/qtest.rst
@@ -2,6 +2,12 @@
 QTest Device Emulation Testing Framework

+.. toctree::
+   :hidden:
+   qgraph
QTest is a device emulation testing framework. It can be very useful to test device models; it could also control certain aspects of QEMU (such as virtual
 clock stepping), with a special purpose "qtest" protocol.  Refer to
@@ -24,6 +30,9 @@ On top of libqtest, a higher level library, ``libqos``, was created to
 encapsulate common tasks of device drivers, such as memory management and
 communicating with system buses or devices. Many virtual device tests use
 libqos instead of directly calling into libqtest.
+Libqos also offers the qgraph API to increase each test coverage and
+automate QEMU command line arguments and devices setup.
+Refer to :ref:`qgraph` for Qgraph explanation and API.

 Steps to add a new QTest case are:


Add hidden toctree because the new file must be linked by at least one, and reference qgraph in the text using the anchor.

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 1dcce3bbed..f0038f8722 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -12,6 +12,7 @@ Contents:

 .. toctree::
    :maxdepth: 2
+   :includehidden:

@@ -24,7 +25,6 @@ Contents:
-   qgraph


Allow showing the hidden toctree in the docs/devel index, so that the link is visible

End result:
- no visible change in docs/index
- qgraph link visible in docs/devel/index
- qgraph linked as text link in qtree

Thank you,

reply via email to

[Prev in Thread] Current Thread [Next in Thread]