1. Patchew
  2. QEMU
  3. [PATCH v2 00/62] docs: Add new QAPI transmogrifier
  4. View patch

[PATCH v2 42/62] docs/qapidoc: add visit_freeform() method

John Snow posted 62 patches 3 weeks, 4 days ago
There is a newer version of this series
[PATCH v2 42/62] docs/qapidoc: add visit_freeform() method
Posted by John Snow 3 weeks, 4 days ago 
Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/sphinx/qapidoc.py | 50 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 6de8c900543..cf5dbb0133d 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -29,6 +29,7 @@
 from contextlib import contextmanager
 import os
 from pathlib import Path
+import re
 import sys
 from typing import TYPE_CHECKING
 
@@ -55,6 +56,8 @@
         Sequence,
     )
 
+    from qapi.parser import QAPIDoc
+
     from sphinx.application import Sphinx
     from sphinx.util.typing import ExtensionMetadata
 
@@ -130,6 +133,53 @@ def visit_module(self, path: str) -> None:
         self.add_line_raw(f".. qapi:module:: {name}", path, 1)
         self.ensure_blank_line()
 
+    def visit_freeform(self, doc: QAPIDoc) -> None:
+        # TODO: Once the old qapidoc transformer is deprecated, freeform
+        # sections can be updated to pure rST, and this transformed removed.
+        #
+        # For now, translate our micro-format into rST. Code adapted
+        # from Peter Maydell's freeform().
+
+        assert len(doc.all_sections) == 1, doc.all_sections
+        body = doc.all_sections[0]
+        text = body.text
+        info = doc.info
+
+        if re.match(r"=+ ", text):
+            # Section/subsection heading (if present, will always be the
+            # first line of the block)
+            (heading, _, text) = text.partition("\n")
+            (leader, _, heading) = heading.partition(" ")
+            level = len(leader) + 1  # Implicit +1 for heading in .rST stub
+
+            # https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
+            markers = {
+                1: "#",
+                2: "*",
+                3: "=",
+                4: "-",
+                5: "^",
+                6: '"',
+            }
+            overline = level <= 2
+            marker = markers[level]
+
+            self.ensure_blank_line()
+            # This credits all 2 or 3 lines to the single source line.
+            if overline:
+                self.add_line(marker * len(heading), info)
+            self.add_line(heading, info)
+            self.add_line(marker * len(heading), info)
+            self.ensure_blank_line()
+
+            # Eat blank line(s) and advance info
+            trimmed = text.lstrip("\n")
+            text = trimmed
+            info = info.next_line(len(text) - len(trimmed) + 1)
+
+        self.add_lines(text, info)
+        self.ensure_blank_line()
+
 
 class QAPISchemaGenDepVisitor(QAPISchemaVisitor):
     """A QAPI schema visitor which adds Sphinx dependencies each module
-- 
2.48.1
Re: [PATCH v2 42/62] docs/qapidoc: add visit_freeform() method
Posted by Markus Armbruster 3 weeks, 3 days ago 
John Snow <jsnow@redhat.com> writes:

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  docs/sphinx/qapidoc.py | 50 ++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 50 insertions(+)
>
> diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> index 6de8c900543..cf5dbb0133d 100644
> --- a/docs/sphinx/qapidoc.py
> +++ b/docs/sphinx/qapidoc.py
> @@ -29,6 +29,7 @@
>  from contextlib import contextmanager
>  import os
>  from pathlib import Path
> +import re
>  import sys
>  from typing import TYPE_CHECKING
>  
> @@ -55,6 +56,8 @@
>          Sequence,
>      )
>  
> +    from qapi.parser import QAPIDoc
> +
>      from sphinx.application import Sphinx
>      from sphinx.util.typing import ExtensionMetadata
>  
> @@ -130,6 +133,53 @@ def visit_module(self, path: str) -> None:
>          self.add_line_raw(f".. qapi:module:: {name}", path, 1)
>          self.ensure_blank_line()
>  
> +    def visit_freeform(self, doc: QAPIDoc) -> None:
> +        # TODO: Once the old qapidoc transformer is deprecated, freeform
> +        # sections can be updated to pure rST, and this transformed removed.
> +        #
> +        # For now, translate our micro-format into rST. Code adapted
> +        # from Peter Maydell's freeform().
> +
> +        assert len(doc.all_sections) == 1, doc.all_sections
> +        body = doc.all_sections[0]
> +        text = body.text
> +        info = doc.info
> +
> +        if re.match(r"=+ ", text):
> +            # Section/subsection heading (if present, will always be the
> +            # first line of the block)
> +            (heading, _, text) = text.partition("\n")
> +            (leader, _, heading) = heading.partition(" ")
> +            level = len(leader) + 1  # Implicit +1 for heading in .rST stub

I find "in .rST stub" less than clear.  Could we use the filename?

> +
> +            # https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
> +            markers = {
> +                1: "#",
> +                2: "*",
> +                3: "=",
> +                4: "-",
> +                5: "^",
> +                6: '"',
> +            }

Suggest

               markers = '#*=-^".

> +            overline = level <= 2
> +            marker = markers[level]
> +
> +            self.ensure_blank_line()
> +            # This credits all 2 or 3 lines to the single source line.
> +            if overline:
> +                self.add_line(marker * len(heading), info)
> +            self.add_line(heading, info)
> +            self.add_line(marker * len(heading), info)
> +            self.ensure_blank_line()
> +
> +            # Eat blank line(s) and advance info
> +            trimmed = text.lstrip("\n")
> +            text = trimmed
> +            info = info.next_line(len(text) - len(trimmed) + 1)
> +
> +        self.add_lines(text, info)
> +        self.ensure_blank_line()
> +
>  
>  class QAPISchemaGenDepVisitor(QAPISchemaVisitor):
>      """A QAPI schema visitor which adds Sphinx dependencies each module
Re: [PATCH v2 42/62] docs/qapidoc: add visit_freeform() method
Posted by John Snow 3 weeks, 2 days ago 
On Sun, Mar 9, 2025 at 5:01 PM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> >  docs/sphinx/qapidoc.py | 50 ++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 50 insertions(+)
> >
> > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> > index 6de8c900543..cf5dbb0133d 100644
> > --- a/docs/sphinx/qapidoc.py
> > +++ b/docs/sphinx/qapidoc.py
> > @@ -29,6 +29,7 @@
> >  from contextlib import contextmanager
> >  import os
> >  from pathlib import Path
> > +import re
> >  import sys
> >  from typing import TYPE_CHECKING
> >
> > @@ -55,6 +56,8 @@
> >          Sequence,
> >      )
> >
> > +    from qapi.parser import QAPIDoc
> > +
> >      from sphinx.application import Sphinx
> >      from sphinx.util.typing import ExtensionMetadata
> >
> > @@ -130,6 +133,53 @@ def visit_module(self, path: str) -> None:
> >          self.add_line_raw(f".. qapi:module:: {name}", path, 1)
> >          self.ensure_blank_line()
> >
> > +    def visit_freeform(self, doc: QAPIDoc) -> None:
> > +        # TODO: Once the old qapidoc transformer is deprecated, freeform
> > +        # sections can be updated to pure rST, and this transformed
> removed.
> > +        #
> > +        # For now, translate our micro-format into rST. Code adapted
> > +        # from Peter Maydell's freeform().
> > +
> > +        assert len(doc.all_sections) == 1, doc.all_sections
> > +        body = doc.all_sections[0]
> > +        text = body.text
> > +        info = doc.info
> > +
> > +        if re.match(r"=+ ", text):
> > +            # Section/subsection heading (if present, will always be the
> > +            # first line of the block)
> > +            (heading, _, text) = text.partition("\n")
> > +            (leader, _, heading) = heading.partition(" ")
> > +            level = len(leader) + 1  # Implicit +1 for heading in .rST
> stub
>
> I find "in .rST stub" less than clear.  Could we use the filename?
>

No, because the filename is "wherever the qapi-doc directive is written". I
adjusted the comment and will re-spin.


>
> > +
> > +            #
> https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
> > +            markers = {
> > +                1: "#",
> > +                2: "*",
> > +                3: "=",
> > +                4: "-",
> > +                5: "^",
> > +                6: '"',
> > +            }
>
> Suggest
>
>                markers = '#*=-^".
>

Done.


>
> > +            overline = level <= 2
> > +            marker = markers[level]
> > +
> > +            self.ensure_blank_line()
> > +            # This credits all 2 or 3 lines to the single source line.
> > +            if overline:
> > +                self.add_line(marker * len(heading), info)
> > +            self.add_line(heading, info)
> > +            self.add_line(marker * len(heading), info)
> > +            self.ensure_blank_line()
> > +
> > +            # Eat blank line(s) and advance info
> > +            trimmed = text.lstrip("\n")
> > +            text = trimmed
> > +            info = info.next_line(len(text) - len(trimmed) + 1)
> > +
> > +        self.add_lines(text, info)
> > +        self.ensure_blank_line()
> > +
> >
> >  class QAPISchemaGenDepVisitor(QAPISchemaVisitor):
> >      """A QAPI schema visitor which adds Sphinx dependencies each module
>
>

Patchew 2.1-devel-b67e4c2

© 2016 - 2025 Red Hat, Inc.