aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJohn Snow <jsnow@redhat.com>2025-06-18 12:53:50 -0400
committerMarkus Armbruster <armbru@redhat.com>2025-07-14 10:08:06 +0200
commite56c683bae9d1dc1b637029a0595225499ef7248 (patch)
treedbaa35efb463f58af54c04c440be176f02a8e968
parent66c83cdd91c07575ebf30bb45da8cc5df8041c29 (diff)
downloadqemu-e56c683bae9d1dc1b637029a0595225499ef7248.zip
qemu-e56c683bae9d1dc1b637029a0595225499ef7248.tar.gz
qemu-e56c683bae9d1dc1b637029a0595225499ef7248.tar.bz2
docs/sphinx: parse @references in freeform text
Oversight in the new qapidoc transmogrifier: @references in freeform documentation blocks were not being transformed to literals. This fixes that, and the next patch ensures that we're testing for this O:-) Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20250618165353.1980365-3-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
-rw-r--r--docs/sphinx/qapidoc.py10
1 files changed, 7 insertions, 3 deletions
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 5374dee..adc14ad 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -218,6 +218,11 @@ class Transmogrifier:
typ = self.format_type(member)
self.add_field(kind, member.name, body, info, typ)
+ @staticmethod
+ def reformat_arobase(text: str) -> str:
+ """ reformats @var to ``var`` """
+ return re.sub(r"@([\w-]+)", r"``\1``", text)
+
# Transmogrification helpers
def visit_paragraph(self, section: QAPIDoc.Section) -> None:
@@ -361,8 +366,7 @@ class Transmogrifier:
# Add sections in source order:
for i, section in enumerate(sections):
- # @var is translated to ``var``:
- section.text = re.sub(r"@([\w-]+)", r"``\1``", section.text)
+ section.text = self.reformat_arobase(section.text)
if section.kind == QAPIDoc.Kind.PLAIN:
self.visit_paragraph(section)
@@ -405,7 +409,7 @@ class Transmogrifier:
assert len(doc.all_sections) == 1, doc.all_sections
body = doc.all_sections[0]
- text = body.text
+ text = self.reformat_arobase(body.text)
info = doc.info
if re.match(r"=+ ", text):