wrong rendering of multi-line "Return" section

[carlodri]

My source docstring inside a class method (correct indent of multiple lines):

        Returns:
            ndarray: a 2-D ``int16`` numpy array with dimensions :math:`(n_e, 2)` where
                the rows represent the :math:`(x, y)` coordinates of the :math:`n_e` events
                detected in the frame.

renders badly in this way:

whereas if I change it to this (wrong indentation of multiple lines):

        Returns:
            ndarray: a 2-D ``int16`` numpy array with dimensions :math:`(n_e, 2)` where
            the rows represent the :math:`(x, y)` coordinates of the :math:`n_e` events
            detected in the frame.

it renders correctly to:

I'm using the sphinx_rtd_theme but a similar issue occurs with the default alabaster theme.

[ExplodingCabbage]

Not sure whether anything should change in Napoleon, but for whatever it's worth, you can also get the result you want by using this indentation which I don't think is incorrect in any way:

Returns:
    ndarray:
        a 2-D ``int16`` numpy array with dimensions :math:`(n_e, 2)` where
        the rows represent the :math:`(x, y)` coordinates of the :math:`n_e` events
        detected in the frame.

[carlodri]

thanks @ExplodingCabbage, I will try that! However, as per the examples in the documentation the first syntax I showed should be correct, whereas it doesn't work properly.

[baylessj]

It looks to me like from this portion of the Google python styleguide: https://google.github.io/styleguide/pyguide.html#doc-function-returns that all of the Returns: code should all be at the same level of indentation, but it seems confusing given that this is not the case for arguments.

I'm not sure if the ideal behavior would be to have the additional level of indentation in return values be accepted or if there should be a note in the docs/a warning thrown when doing this style of indentation. Either way, I also find the current behavior less than ideal.

[GiliR4t1qbit]

Any news on a solution to this issue or a workaround? I'm in the same position. The style guide and examples do not state clearly what should happen, but given the way it is for arguments, I believe @carlodri is right.