multiline returns parsed incorrectly

[rsokolewicz]

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

    Returns
    -------
    :
        Something A
    :
        Something B

and build documentation with sphinx w(with autopi extension) this wiill raise a warning

WARNING: Definition list ends without a blank line; unexpected unindent.

looking at the .rst that is created, I see

   :returns: * Something A
             * Something B

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 with scanpydoc. I don't have a minimal failing example, but if that would be useful I can spend some time to provide one for you.

[flying-sheep]

I see! 0.12 tries to undo a hack introduced by sphinx-autodoc-typehints here:

https://github.com/theislab/scanpydoc/blob/bf6eef2ff7b4fb17a3bedb080ae328c2d74dd803/src/scanpydoc/elegant_typehints/_return_patch_numpydoc.py#L14-L17

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.

[rsokolewicz]

Thanks!

[flying-sheep]

@rsokolewicz what’s that return section supposed to look like?

Where is that standalone colon documented?

[rsokolewicz]

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

[flying-sheep]

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.

[rsokolewicz]

amazing, thanks! :)

[flying-sheep]

always happy when my works helps someone