| Message ID | 20241213021827.2956769-11-jsnow@redhat.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | docs: add basic sphinx-domain rST generator to qapidoc | expand |
John Snow <jsnow@redhat.com> writes: > Signed-off-by: John Snow <jsnow@redhat.com> > --- > docs/sphinx/qapidoc.py | 47 ++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 47 insertions(+) > > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py > index 7d2f7bfb415..6f8f69077b1 100644 > --- a/docs/sphinx/qapidoc.py > +++ b/docs/sphinx/qapidoc.py > @@ -133,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) -> None: > + # Once the old qapidoc transformer is deprecated, > + # freeform sections can be transformed into pure rST. > + # > + # 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) We could instead eat newlines one at a time, calling .next_line() without an argument for each newline eaten. Less efficient, but won't matter here. Possibly easier to understand. > + > + self.add_lines(text, info) > + self.ensure_blank_line() > + > > # Disable black auto-formatter until re-enabled: > # fmt: off
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 7d2f7bfb415..6f8f69077b1 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -133,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) -> None: + # Once the old qapidoc transformer is deprecated, + # freeform sections can be transformed into pure rST. + # + # 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() + # Disable black auto-formatter until re-enabled: # fmt: off
Signed-off-by: John Snow <jsnow@redhat.com> --- docs/sphinx/qapidoc.py | 47 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+)