On 9/25/20 4:59 AM, Markus Armbruster wrote:
John Snow <js...@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 <js...@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 <arm...@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
