qemu-devel.nongnu.org archive mirror
 help / color / mirror / Atom feed
From: John Snow <jsnow@redhat.com>
To: qemu-devel@nongnu.org
Cc: "Peter Maydell" <peter.maydell@linaro.org>,
	"John Snow" <jsnow@redhat.com>,
	"Daniel P. Berrangé" <berrange@redhat.com>,
	"Eric Blake" <eblake@redhat.com>,
	"Michael Roth" <michael.roth@amd.com>,
	"Thomas Huth" <thuth@redhat.com>,
	"Philippe Mathieu-Daudé" <philmd@linaro.org>,
	"Alex Bennée" <alex.bennee@linaro.org>,
	"Markus Armbruster" <armbru@redhat.com>
Subject: [PATCH v3 35/63] docs/qapidoc: add transmogrifier stub
Date: Mon, 10 Mar 2025 23:42:33 -0400	[thread overview]
Message-ID: <20250311034303.75779-36-jsnow@redhat.com> (raw)
In-Reply-To: <20250311034303.75779-1-jsnow@redhat.com>

This commit adds a stubbed option to the qapi-doc directive that opts-in
to the new rST generator; the implementation of which will follow in
subsequent commits.

Once all QAPI documents have been converted, this option and the old
qapidoc implementation can be dropped.

Note that moving code outside of the try...except block has no impact
because the code moved outside of that block does not ever raise a
QAPIError.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/sphinx/qapidoc.py | 41 ++++++++++++++++++++++++++++-------------
 1 file changed, 28 insertions(+), 13 deletions(-)

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index d622398f1da..dc72f3fd3f3 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -452,9 +452,9 @@ def _parse_text_into_node(self, doctext, node):
         rstlist.append("", self._cur_doc.info.fname, self._cur_doc.info.line)
         self._sphinx_directive.do_parse(rstlist, node)
 
-    def get_document_nodes(self):
-        """Return the list of docutils nodes which make up the document"""
-        return self._top_node.children
+    def get_document_node(self):
+        """Return the root docutils node which makes up the document"""
+        return self._top_node
 
 
 # Turn the black formatter on for the rest of the file.
@@ -503,7 +503,10 @@ class QAPIDocDirective(NestedDirective):
 
     required_argument = 1
     optional_arguments = 1
-    option_spec = {"qapifile": directives.unchanged_required}
+    option_spec = {
+        "qapifile": directives.unchanged_required,
+        "transmogrify": directives.flag,
+    }
     has_content = False
 
     def new_serialno(self):
@@ -511,10 +514,24 @@ def new_serialno(self):
         env = self.state.document.settings.env
         return "qapidoc-%d" % env.new_serialno("qapidoc")
 
+    def transmogrify(self, schema) -> nodes.Element:
+        raise NotImplementedError
+
+    def legacy(self, schema) -> nodes.Element:
+        vis = QAPISchemaGenRSTVisitor(self)
+        vis.visit_begin(schema)
+        for doc in schema.docs:
+            if doc.symbol:
+                vis.symbol(doc, schema.lookup_entity(doc.symbol))
+            else:
+                vis.freeform(doc)
+        return vis.get_document_node()
+
     def run(self):
         env = self.state.document.settings.env
         qapifile = env.config.qapidoc_srctree + "/" + self.arguments[0]
         qapidir = os.path.dirname(qapifile)
+        transmogrify = "transmogrify" in self.options
 
         try:
             schema = QAPISchema(qapifile)
@@ -522,20 +539,18 @@ def run(self):
             # First tell Sphinx about all the schema files that the
             # output documentation depends on (including 'qapifile' itself)
             schema.visit(QAPISchemaGenDepVisitor(env, qapidir))
-
-            vis = QAPISchemaGenRSTVisitor(self)
-            vis.visit_begin(schema)
-            for doc in schema.docs:
-                if doc.symbol:
-                    vis.symbol(doc, schema.lookup_entity(doc.symbol))
-                else:
-                    vis.freeform(doc)
-            return vis.get_document_nodes()
         except QAPIError as err:
             # Launder QAPI parse errors into Sphinx extension errors
             # so they are displayed nicely to the user
             raise ExtensionError(str(err)) from err
 
+        if transmogrify:
+            contentnode = self.transmogrify(schema)
+        else:
+            contentnode = self.legacy(schema)
+
+        return contentnode.children
+
 
 class QMPExample(CodeBlock, NestedDirective):
     """
-- 
2.48.1



  parent reply	other threads:[~2025-03-11  3:59 UTC|newest]

Thread overview: 74+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2025-03-11  3:41 [PATCH v3 00/63] docs: Add new QAPI transmogrifier John Snow
2025-03-11  3:41 ` [PATCH v3 01/63] do-not-merge John Snow
2025-03-11  3:42 ` [PATCH v3 02/63] qapi: shush pylint up John Snow
2025-03-11  6:59   ` Markus Armbruster
2025-03-11  3:42 ` [PATCH v3 03/63] docs/sphinx: create QAPI domain extension stub John Snow
2025-03-11  3:42 ` [PATCH v3 04/63] docs/sphinx: add compat.py module and nested_parse helper John Snow
2025-03-11  3:42 ` [PATCH v3 05/63] docs/qapi-domain: add QAPI domain object registry John Snow
2025-03-11  3:42 ` [PATCH v3 06/63] docs/qapi-domain: add QAPI index John Snow
2025-03-11  3:42 ` [PATCH v3 07/63] docs/qapi-domain: add resolve_any_xref() John Snow
2025-03-11  3:42 ` [PATCH v3 08/63] docs/qapi-domain: add QAPI xref roles John Snow
2025-03-11  3:42 ` [PATCH v3 09/63] docs/qapi-domain: add compatibility node classes John Snow
2025-03-11  3:42 ` [PATCH v3 10/63] docs/qapi-domain: Add QAPIDescription abstract class John Snow
2025-03-11  3:42 ` [PATCH v3 11/63] docs/qapi-domain: add qapi:module directive John Snow
2025-03-11  3:42 ` [PATCH v3 12/63] docs/qapi-domain: add QAPIObject class John Snow
2025-03-11  3:42 ` [PATCH v3 13/63] docs/qapi-domain: add qapi:command directive John Snow
2025-03-11  3:42 ` [PATCH v3 14/63] docs/qapi-domain: add :since: directive option John Snow
2025-03-11  3:42 ` [PATCH v3 15/63] docs/qapi-domain: add "Arguments:" field lists John Snow
2025-03-11  3:42 ` [PATCH v3 16/63] docs/qapi-domain: add "Features:" " John Snow
2025-03-11  3:42 ` [PATCH v3 17/63] docs/qapi-domain: add "Errors:" " John Snow
2025-03-11  3:42 ` [PATCH v3 18/63] docs/qapi-domain: add "Return:" " John Snow
2025-03-11  3:42 ` [PATCH v3 19/63] docs/qapi-domain: add qapi:enum directive John Snow
2025-03-11  3:42 ` [PATCH v3 20/63] docs/qapi-domain: add qapi:alternate directive John Snow
2025-03-11  3:42 ` [PATCH v3 21/63] docs/qapi-domain: add qapi:event directive John Snow
2025-03-11  3:42 ` [PATCH v3 22/63] docs/qapi-domain: add qapi:object directive John Snow
2025-03-11  3:42 ` [PATCH v3 23/63] docs/qapi-domain: add :deprecated: directive option John Snow
2025-03-11  3:42 ` [PATCH v3 24/63] docs/qapi-domain: add :unstable: " John Snow
2025-03-11  3:42 ` [PATCH v3 25/63] docs/qapi-domain: add :ifcond: " John Snow
2025-03-11  3:42 ` [PATCH v3 26/63] docs/qapi-domain: add warnings for malformed field lists John Snow
2025-03-11  3:42 ` [PATCH v3 27/63] docs/qapi-domain: add type cross-refs to " John Snow
2025-03-11  3:42 ` [PATCH v3 28/63] docs/qapi-domain: add CSS styling John Snow
2025-03-11  3:42 ` [PATCH v3 29/63] docs/qapi-domain: add XREF compatibility goop for Sphinx < 4.1 John Snow
2025-03-11  3:42 ` [PATCH v3 30/63] docs/qapi-domain: warn when QAPI domain xrefs fail to resolve John Snow
2025-03-11  3:42 ` [PATCH v3 31/63] docs/qapi-domain: Fix error context reporting in Sphinx 5.x and 6.x John Snow
2025-03-11  3:42 ` [PATCH v3 32/63] qapi/parser: adjust info location for doc body section John Snow
2025-03-11  7:01   ` Markus Armbruster
2025-03-11  3:42 ` [PATCH v3 33/63] qapi: clean up encoding of section kinds John Snow
2025-03-11  7:02   ` Markus Armbruster
2025-03-11  3:42 ` [PATCH v3 34/63] qapi/schema: add __repr__ to QAPIDoc.Section John Snow
2025-03-11  7:03   ` Markus Armbruster
2025-03-11  3:42 ` John Snow [this message]
2025-03-11  3:42 ` [PATCH v3 36/63] docs/qapidoc: split old implementation into qapidoc_legacy.py John Snow
2025-03-11  3:42 ` [PATCH v3 37/63] docs/qapidoc: Fix static typing on qapidoc.py John Snow
2025-03-11  3:42 ` [PATCH v3 38/63] do-not-merge John Snow
2025-03-11  3:42 ` [PATCH v3 39/63] docs/qapidoc: add transmogrifier class stub John Snow
2025-03-11  3:42 ` [PATCH v3 40/63] docs/qapidoc: add visit_module() method John Snow
2025-03-11  3:42 ` [PATCH v3 41/63] qapi/source: allow multi-line QAPISourceInfo advancing John Snow
2025-03-11  3:42 ` [PATCH v3 42/63] docs/qapidoc: add visit_freeform() method John Snow
2025-03-11  3:42 ` [PATCH v3 43/63] docs/qapidoc: add preamble() method John Snow
2025-03-11  3:42 ` [PATCH v3 44/63] docs/qapidoc: add visit_paragraph() method John Snow
2025-03-11  3:42 ` [PATCH v3 45/63] docs/qapidoc: add visit_errors() method John Snow
2025-03-11  3:42 ` [PATCH v3 46/63] docs/qapidoc: add format_type() method John Snow
2025-03-11  3:42 ` [PATCH v3 47/63] docs/qapidoc: add add_field() and generate_field() helper methods John Snow
2025-03-11  3:42 ` [PATCH v3 48/63] docs/qapidoc: add visit_feature() method John Snow
2025-03-11  3:42 ` [PATCH v3 49/63] docs/qapidoc: prepare to record entity being transmogrified John Snow
2025-03-11  3:42 ` [PATCH v3 50/63] docs/qapidoc: add visit_returns() method John Snow
2025-03-11  3:42 ` [PATCH v3 51/63] docs/qapidoc: add visit_member() method John Snow
2025-03-11  3:42 ` [PATCH v3 52/63] docs/qapidoc: add visit_sections() method John Snow
2025-03-11  8:34   ` Markus Armbruster
2025-03-11  3:42 ` [PATCH v3 53/63] docs/qapidoc: add visit_entity() John Snow
2025-03-11  3:42 ` [PATCH v3 54/63] docs/qapidoc: implement transmogrify() method John Snow
2025-03-11  8:52   ` Markus Armbruster
2025-03-11  3:42 ` [PATCH v3 55/63] docs/qapidoc: process @foo into ``foo`` John Snow
2025-03-11  3:42 ` [PATCH v3 56/63] docs/qapidoc: add intermediate output debugger John Snow
2025-03-11  3:42 ` [PATCH v3 57/63] docs/qapidoc: Add "the members of" pointers John Snow
2025-03-11  3:42 ` [PATCH v3 58/63] docs/qapidoc: generate entries for undocumented members John Snow
2025-03-11  9:22   ` Markus Armbruster
2025-03-11  3:42 ` [PATCH v3 59/63] qapi/parser: add undocumented stub members to all_sections John Snow
2025-03-11  7:04   ` Markus Armbruster
2025-03-11  8:14     ` Markus Armbruster
2025-03-11  3:42 ` [PATCH v3 60/63] docs: disambiguate cross-references John Snow
2025-03-11  3:42 ` [PATCH v3 61/63] docs: enable qapidoc transmogrifier for QEMU QMP Reference John Snow
2025-03-11  3:43 ` [PATCH v3 62/63] docs: add qapi-domain syntax documentation John Snow
2025-03-11  3:43 ` [PATCH v3 63/63] MAINTAINERS: Add jsnow as maintainer for Sphinx documentation John Snow
2025-03-11  8:52 ` [PATCH v3 00/63] docs: Add new QAPI transmogrifier Markus Armbruster

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20250311034303.75779-36-jsnow@redhat.com \
    --to=jsnow@redhat.com \
    --cc=alex.bennee@linaro.org \
    --cc=armbru@redhat.com \
    --cc=berrange@redhat.com \
    --cc=eblake@redhat.com \
    --cc=michael.roth@amd.com \
    --cc=peter.maydell@linaro.org \
    --cc=philmd@linaro.org \
    --cc=qemu-devel@nongnu.org \
    --cc=thuth@redhat.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).