Re: [PATCH v3 05/47] qapi/doc.py: Change code templates from function to string

[John Snow]

On 9/25/20 4:59 AM, Markus Armbruster wrote:
> John Snow <jsnow@redhat.com> writes:
>
> > For whatever reason, when these are stored as functions instead of
> > strings, it confuses sphinx-autodoc into believing them to be
> > docstrings, and it chokes on the syntax.
> >
> > Keeping them as dumb strings instead avoids the problem.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
>
> Quoting my review of the patch that added it: "This .format business is
> perhaps a bit too clever.  But let's move on."

It seems perfectly fine, and I have no real explanation for why it 
confuses autodoc.

I think autodoc is using regex that it maybe shouldn't be to identify 
some constructs instead of the proper Python AST. I looked extremely 
briefly but made the assessment it wasn't going to be quick.

> doc.py is about to be replaced, obsoleting this patch.  Regardless:
> Reviewed-by: Markus Armbruster <armbru@redhat.com>

Yes, understood -- until such time as it is actually deleted, I am 
keeping it updated with the style I am trying to enforce just to make my 
own life simpler.

It's no problem to just trash it when the time comes, but in this case I 
wanted to explore what stopped us from using Sphinx autodoc earnestly -- 
and it just so happened that this was the sticking point.

Thanks for looking!

--js