Closed rsokolewicz closed 7 months ago
I see! 0.12 tries to undo a hack introduced by sphinx-autodoc-typehints
here:
You can circumvent it for now by giving the return tuple entries names, like
Returns
-------
A
Something A
B
Something B
but I’ll try to figure out a more robust way to undo sphinx-autodoc-typehints
’ hack that doesn’t affect manual :
lines.
Thanks!
@rsokolewicz what’s that return section supposed to look like?
Where is that standalone colon documented?
According the numpy doc recommendations, the following should be excepted:
Returns
--------
A
something A
(where A is the return type)
Returns
--------
a : A
something A
(where a is label/name, and A is return type)
it doesn't say to explicit what is accepted for multiline returns, but my guess is
Returns
--------
A
something A
B
something B
Returns
--------
a : A
something A
b : B
something B
Returns
--------
A
something A
b : B
something B
We have a lot of old documentation that also uses standalone :
though I read that is not according to the numpy doc standards (i.e. one should always specify a return type, while return label/name is optional):
Returns
--------
:
something A
and
Returns
--------
:
something A
:
something B
OK! scanpydoc deviates from numpy style by allowing prose return sections and by encouraging you to put type annotations in the … type annotations instead of the docstring.
I have a patch ready that allows for standalone colons.
amazing, thanks! :)
always happy when my works helps someone
In one of our packages we run into problems when using
scanpydoc==0.12
(0.11.0
works fine).If I have a class with the following docstring
and build documentation with sphinx w(with autopi extension) this wiill raise a warning
looking at the .rst that is created, I see
so it seems some parsing is done incorrectly?
Also, not sure if it is something due to
scanpydoc
or that another sphinx extension does not play nicely withscanpydoc
. I don't have a minimal failing example, but if that would be useful I can spend some time to provide one for you.