diff options
| author | John Snow <jsnow@redhat.com> | 2025-06-18 12:53:52 -0400 |
|---|---|---|
| committer | Markus Armbruster <armbru@redhat.com> | 2025-07-14 10:08:27 +0200 |
| commit | 6c10778826a873b9012d95e63298a6f879debcaa (patch) | |
| tree | 9707775416b8a85c047ef42facefb1c42eb1a3bd /docs/sphinx/qapidoc.py | |
| parent | 8d789c8cdb8de2cae39f217b6c9607ac9c036c8c (diff) | |
| download | focaccia-qemu-6c10778826a873b9012d95e63298a6f879debcaa.tar.gz focaccia-qemu-6c10778826a873b9012d95e63298a6f879debcaa.zip | |
docs/sphinx: remove special parsing for freeform sections
Remove the QAPI doc section heading syntax, use plain rST section headings instead. Tests and documentation are updated to match. Interestingly, Plain rST headings work fine before this patch, except for over- and underlining with '=', which the doc parser rejected as invalid QAPI doc section heading in free-form comments. Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20250618165353.1980365-5-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Add more detail to commit message] Signed-off-by: Markus Armbruster <armbru@redhat.com>
Diffstat (limited to 'docs/sphinx/qapidoc.py')
| -rw-r--r-- | docs/sphinx/qapidoc.py | 37 |
1 files changed, 1 insertions, 36 deletions
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index d5d2b5eeb5..b794cde697 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -399,44 +399,9 @@ class Transmogrifier: 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 = self.reformat_arobase(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(" ") - # Implicit +1 for heading in the containing .rst doc - level = len(leader) + 1 - - # https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections - 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.add_lines(self.reformat_arobase(body.text), doc.info) self.ensure_blank_line() def visit_entity(self, ent: QAPISchemaDefinition) -> None: |