[v1] docs: add basic sphinx-domain rST generator to qapidoc

[PATCH 16/23] docs/qapidoc: add visit_feature() method

Posted by John Snow 4 months, 3 weeks ago

The format_type() method is adjusted here to return None for features,
because Features don't have documented types. This makes
generate_field() safe to use for features.

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

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 7efe2d656c0..02f434c09ab 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -187,6 +187,15 @@ def visit_paragraph(self, section: QAPIDoc.Section) -> None:
         self.add_lines(section.text, section.info)
         self.ensure_blank_line()
 
+    def visit_feature(self, section: QAPIDoc.ArgSection) -> None:
+        # FIXME - ifcond for features is not handled at all yet!
+        # Proposal: decorate the right-hand column with some graphical
+        # element to indicate conditional availability?
+        assert section.text  # Guaranteed by parser.py
+        assert section.member
+
+        self.generate_field("feat", section.member, section.text, section.info)
+
     def visit_errors(self, section: QAPIDoc.Section) -> None:
         # FIXME: the formatting for errors may be inconsistent and may
         # or may not require different newline placement to ensure
-- 
2.47.0

Re: [PATCH 16/23] docs/qapidoc: add visit_feature() method

Posted by Markus Armbruster 4 months, 2 weeks ago

John Snow <jsnow@redhat.com> writes:

> The format_type() method is adjusted here to return None for features,
> because Features don't have documented types. This makes
> generate_field() safe to use for features.

I'm confused: the patch doesn't touch format_type().

>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  docs/sphinx/qapidoc.py | 9 +++++++++
>  1 file changed, 9 insertions(+)
>
> diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> index 7efe2d656c0..02f434c09ab 100644
> --- a/docs/sphinx/qapidoc.py
> +++ b/docs/sphinx/qapidoc.py
> @@ -187,6 +187,15 @@ def visit_paragraph(self, section: QAPIDoc.Section) -> None:
>          self.add_lines(section.text, section.info)
>          self.ensure_blank_line()
>  
> +    def visit_feature(self, section: QAPIDoc.ArgSection) -> None:
> +        # FIXME - ifcond for features is not handled at all yet!
> +        # Proposal: decorate the right-hand column with some graphical
> +        # element to indicate conditional availability?
> +        assert section.text  # Guaranteed by parser.py
> +        assert section.member
> +
> +        self.generate_field("feat", section.member, section.text, section.info)
> +
>      def visit_errors(self, section: QAPIDoc.Section) -> None:
>          # FIXME: the formatting for errors may be inconsistent and may
>          # or may not require different newline placement to ensure

Re: [PATCH 16/23] docs/qapidoc: add visit_feature() method

Posted by John Snow 4 months ago

On Fri, Dec 20, 2024 at 9:21 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > The format_type() method is adjusted here to return None for features,
> > because Features don't have documented types. This makes
> > generate_field() safe to use for features.
>
> I'm confused: the patch doesn't touch format_type().
>

Patch refactoring booboo, sorry for the confusion.


>
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> >  docs/sphinx/qapidoc.py | 9 +++++++++
> >  1 file changed, 9 insertions(+)
> >
> > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> > index 7efe2d656c0..02f434c09ab 100644
> > --- a/docs/sphinx/qapidoc.py
> > +++ b/docs/sphinx/qapidoc.py
> > @@ -187,6 +187,15 @@ def visit_paragraph(self, section: QAPIDoc.Section)
> -> None:
> >          self.add_lines(section.text, section.info)
> >          self.ensure_blank_line()
> >
> > +    def visit_feature(self, section: QAPIDoc.ArgSection) -> None:
> > +        # FIXME - ifcond for features is not handled at all yet!
> > +        # Proposal: decorate the right-hand column with some graphical
> > +        # element to indicate conditional availability?
> > +        assert section.text  # Guaranteed by parser.py
> > +        assert section.member
> > +
> > +        self.generate_field("feat", section.member, section.text,
> section.info)
> > +
> >      def visit_errors(self, section: QAPIDoc.Section) -> None:
> >          # FIXME: the formatting for errors may be inconsistent and may
> >          # or may not require different newline placement to ensure
>
>