Re: [PATCH 06/17] sphinx/qapidoc: Do not emit TODO sections into user manuals

[Ani Sinha <anisinha@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 2847 bytes --]

On Fri, Apr 28, 2023 at 4:24 PM Markus Armbruster <armbru@redhat.com> wrote:

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

Reviewed-by: Ani Sinha <anisinha@redhat.com>


> ---
>  docs/devel/qapi-code-gen.rst | 5 +++--
>  docs/sphinx/qapidoc.py       | 3 +++
>  2 files changed, 6 insertions(+), 2 deletions(-)
>
> diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
> index ff7b74bdb2..6386b58881 100644
> --- 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 d791b59492..8f3b9997a1 100644
> --- a/docs/sphinx/qapidoc.py
> +++ b/docs/sphinx/qapidoc.py
> @@ -268,6 +268,9 @@ def _nodes_for_sections(self, doc):
>          """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)
> --
> 2.39.2
>
>

[-- Attachment #2: Type: text/html, Size: 4069 bytes --]