Re: [PATCH v3 2/5] docs/sphinx: parse @references in freeform text

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@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 <jsnow@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!

> +        """ 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):