sphinx/qapidoc: Do not emit TODO sections into user manuals

QAPI doc comments are for QMP users: they go into the "QEMU QMP
Reference Manual" and the "QEMU Storage Daemon QMP Reference Manual".

The doc comment TODO sections are for somebody else, namely for the
people who can do: developers.  Do not emit them into the user
manuals.

This elides the following TODOs:

* SchemaInfoCommand

  # TODO: @success-response (currently irrelevant, because it's QGA, not QMP)

  This is a note to developers adding introspection to the guest
  agent.  It makes no sense to users.

* @query-hotpluggable-cpus

  # TODO: Better documentation; currently there is none.

  This is a reminder for developers.  It doesn't help users.

* @device_add

  # TODO: This command effectively bypasses QAPI completely due to its
  #       "additional arguments" business.  It shouldn't have been added to
  #       the schema in this form.  It should be qapified properly, or
  #       replaced by a properly qapified command.

  Likewise.

Eliding them is an improvement.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-7-armbru@redhat.com>
Reviewed-by: Ani Sinha <anisinha@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index ff7b74bdb27cd3a72ee4295aa4af1ae70bc1f9d0..6386b588819bbc944ed780836477387c6d09b51a 100644 (file)
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -1007,8 +1007,9 @@ A "Since: x.y.z" tagged section lists the release that introduced the
 definition.
 
 An "Example" or "Examples" section is automatically rendered entirely
-as literal fixed-width text.  In other sections, the text is
-formatted, and rST markup can be used.
+as literal fixed-width text.  "TODO" sections are not rendered at all
+(they are for developers, not users of QMP).  In other sections, the
+text is formatted, and rST markup can be used.
 
 For example::
 

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index d791b594923cb707e3cd932a8433943dbeae815f..8f3b9997a1532b4dc3adc90ab373d67fe8861659 100644 (file)
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -268,6 +268,9 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
         """Return list of doctree nodes for additional sections"""
         nodelist = []
         for section in doc.sections:
+            if section.name and section.name == 'TODO':
+                # Hide TODO: sections
+                continue
             snode = self._make_section(section.name)
             if section.name and section.name.startswith('Example'):
                 snode += self._nodes_for_example(section.text)