[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 06/17] sphinx/qapidoc: Do not emit TODO sections into user manuals
From: |
Markus Armbruster |
Subject: |
[PULL 06/17] sphinx/qapidoc: Do not emit TODO sections into user manuals |
Date: |
Tue, 9 May 2023 10:00:00 +0200 |
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>
---
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
- [PULL 04/17] meson: Fix to make QAPI generator output depend on main.py, (continued)
- [PULL 04/17] meson: Fix to make QAPI generator output depend on main.py, Markus Armbruster, 2023/05/09
- [PULL 03/17] qapi: Fix crash on stray double quote character, Markus Armbruster, 2023/05/09
- [PULL 01/17] docs/devel/qapi-code-gen: Clean up use of quotes a bit, Markus Armbruster, 2023/05/09
- [PULL 10/17] tests/qapi-schema/doc-good: Improve argument description tests, Markus Armbruster, 2023/05/09
- [PULL 09/17] tests/qapi-schema/doc-good: Improve a comment, Markus Armbruster, 2023/05/09
- [PULL 07/17] qapi: Tidy up a slightly awkward TODO comment, Markus Armbruster, 2023/05/09
- [PULL 08/17] qapi/dump: Indent bulleted lists consistently, Markus Armbruster, 2023/05/09
- [PULL 05/17] Revert "qapi: BlockExportRemoveMode: move comments to TODO", Markus Armbruster, 2023/05/09
- [PULL 13/17] qapi: Relax doc string @name: description indentation rules, Markus Armbruster, 2023/05/09
- [PULL 16/17] qga/qapi-schema: Reformat doc comments to conform to current conventions, Markus Armbruster, 2023/05/09
- [PULL 06/17] sphinx/qapidoc: Do not emit TODO sections into user manuals,
Markus Armbruster <=
- [PULL 12/17] qapi: Rewrite parsing of doc comment section symbols and tags, Markus Armbruster, 2023/05/09
- [PULL 11/17] qapi: Fix argument description indentation stripping, Markus Armbruster, 2023/05/09
- [PULL 15/17] docs/devel/qapi-code-gen: Update doc comment conventions, Markus Armbruster, 2023/05/09
- [PULL 14/17] qapi: Section parameter @indent is no longer used, drop, Markus Armbruster, 2023/05/09
- [PULL 17/17] qapi: Reformat doc comments to conform to current conventions, Markus Armbruster, 2023/05/09
- Re: [PULL 00/17] QAPI patches patches for 2023-05-09, Richard Henderson, 2023/05/09