[v2,52/62] docs/qapidoc: add visit_sections() method

Commit Message

John Snow March 9, 2025, 8:35 a.m. UTC

Implement the actual main dispatch method that processes and handles the
list of doc sections for a given QAPI entity.

Signed-off-by: John Snow <[e-mail]>
---
 docs/sphinx/qapidoc.py | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

Comments

Markus Armbruster March 9, 2025, 9:10 p.m. UTC | #1

John Snow <[e-mail]> writes:

> Implement the actual main dispatch method that processes and handles the
> list of doc sections for a given QAPI entity.
>
> Signed-off-by: John Snow <[e-mail]>
> ---
>  docs/sphinx/qapidoc.py | 25 +++++++++++++++++++++++++
>  1 file changed, 25 insertions(+)
>
> diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> index db11c2ae933..78bec91271f 100644
> --- a/docs/sphinx/qapidoc.py
> +++ b/docs/sphinx/qapidoc.py
> @@ -288,6 +288,31 @@ def preamble(self, ent: QAPISchemaDefinition) -> None:
>  
>          self.ensure_blank_line()
>  
> +    def visit_sections(self, ent: QAPISchemaDefinition) -> None:
> +        sections = ent.doc.all_sections if ent.doc else []
> +
> +        # Add sections *in the order they are documented*:

Would

              # Add sections in source order

be clearer?

> +        for section in sections:
> +            if section.kind == QAPIDoc.Kind.PLAIN:
> +                self.visit_paragraph(section)
> +            elif section.kind == QAPIDoc.Kind.MEMBER:
> +                assert isinstance(section, QAPIDoc.ArgSection)
> +                self.visit_member(section)
> +            elif section.kind == QAPIDoc.Kind.FEATURE:
> +                assert isinstance(section, QAPIDoc.ArgSection)
> +                self.visit_feature(section)
> +            elif section.kind in (QAPIDoc.Kind.SINCE, QAPIDoc.Kind.TODO):
> +                # Since is handled in preamble, TODO is skipped intentionally.
> +                pass
> +            elif section.kind == QAPIDoc.Kind.RETURNS:
> +                self.visit_returns(section)
> +            elif section.kind == QAPIDoc.Kind.ERRORS:
> +                self.visit_errors(section)
> +            else:
> +                assert False
> +
> +        self.ensure_blank_line()
> +
>      # Transmogrification core methods
>  
>      def visit_module(self, path: str) -> None:

Patch

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index db11c2ae933..78bec91271f 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -288,6 +288,31 @@  def preamble(self, ent: QAPISchemaDefinition) -> None:
 
         self.ensure_blank_line()
 
+    def visit_sections(self, ent: QAPISchemaDefinition) -> None:
+        sections = ent.doc.all_sections if ent.doc else []
+
+        # Add sections *in the order they are documented*:
+        for section in sections:
+            if section.kind == QAPIDoc.Kind.PLAIN:
+                self.visit_paragraph(section)
+            elif section.kind == QAPIDoc.Kind.MEMBER:
+                assert isinstance(section, QAPIDoc.ArgSection)
+                self.visit_member(section)
+            elif section.kind == QAPIDoc.Kind.FEATURE:
+                assert isinstance(section, QAPIDoc.ArgSection)
+                self.visit_feature(section)
+            elif section.kind in (QAPIDoc.Kind.SINCE, QAPIDoc.Kind.TODO):
+                # Since is handled in preamble, TODO is skipped intentionally.
+                pass
+            elif section.kind == QAPIDoc.Kind.RETURNS:
+                self.visit_returns(section)
+            elif section.kind == QAPIDoc.Kind.ERRORS:
+                self.visit_errors(section)
+            else:
+                assert False
+
+        self.ensure_blank_line()
+
     # Transmogrification core methods
 
     def visit_module(self, path: str) -> None: