On Fri, Jun 27, 2025, 5:54 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@redhat.com> writes: > > > 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 <js...@redhat.com> > > --- > > docs/sphinx/qapidoc.py | 10 +++++++--- > > 1 file changed, 7 insertions(+), 3 deletions(-) > > > > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py > > index 5374dee8fad..adc14ade456 100644 > > --- a/docs/sphinx/qapidoc.py > > +++ b/docs/sphinx/qapidoc.py > > @@ -218,6 +218,11 @@ def generate_field( > > typ = self.format_type(member) > > self.add_field(kind, member.name, body, info, typ) > > > > + @staticmethod > > + def reformat_arobase(text: str) -> str: > > What's an "arobase"? Inquiring mind wants to know! > French for "at symbol thingie" :) (Intentionally obtuse as an oblique joke, forgive my humor) > > + """ 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 @@ def visit_sections(self, ent: QAPISchemaDefinition) > -> None: > > > > # 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 @@ def visit_freeform(self, doc: QAPIDoc) -> None: > > > > 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): > >
