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

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

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:
>>>     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.

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:

     build-system
     kconfig
@@ -24,7 +25,6 @@ Contents:
     atomics
     stable-process
     qtest
-   qgraph
     decodetree
     secure-coding-practices
     tcg

-------

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,
Emanuele