Instead of just copying docstrings from numpy versions, how about writing the docstrings of the functions in numpy.ma like "This function is numpy.ma version of the function foo. See numpy.foo for details"?

I tend to agree in principle, but I don't think that this is a general solution. While some functions in ma simply use the docstring from their np counterpart , some don't. There are examples of both patterns (and others) in numpy/ma/core.py for example. I am not familiar enough with np.ma to say whether an approach like this would scale well.

(from the conversation in #16300 )

@rossbar It's enough to replace to "This function is ..." only when the function simply copies the docstring in np version. If the function doesn't copy (the function has proper docstring apart from the np version), we don't have to change.

Some functions use neither _frommethod nor _convert2ma, and just copy (foo.__doc__ = np.foo.__doc__). If _convert2ma can be applied for these functions, it is enough to see the getdoc method in _convert2ma, and add the process to prepend numpy. to the links in the docstring which start other than numpy..

If _convert2ma can be applied for these functions, it is enough to see the getdoc method in _convert2ma, and add the process to prepend numpy. to the links in the docstring which start other than numpy.

This would work, though then you'd be automatically overriding any references to np.ma versions of functions when they're defined. Take np.ma.var for instance: there are six references in the See Also section, five of which are references to functions. Of those, two (std and mean) have np.ma counterparts, whereas the other three do not. If you prepend numpy to everything, than you lose the specific references to the ma versions of mean and std. Since the docstrings appear to be simply copied over from the non-masked versions, it doesn't seem like you'd lose anything, but in the case where the ma version of a function has an ma-specific docstring, you'd be overriding the reference to it.

What is the status of this experiment?

Ideally there would be a solution that would add e.g. .. currentmodule's etc. where appropriate when the ma docs are being generated

Could this be done with a custom template option in the autosummary in doc/source/referencemaskedarray.baseclass.rst?

I'll try using template.

Now I work to fix this problem in #17515 .

Modified to prepend ma. instead of numpy.. (see #17515 (comment)).

Thanks @takanori-pskq.