python - 如何使用 NumpyDoc 正确记录属性

Question

我正在管理一个使用 NumpyDoc 样式的包，并且我正在尝试正确记录某些属性的设置器/获取器。

特别是，我遇到了一个问题，即 setter 的文档被 python 忽略，因此所有文档都必须进入 getter。另一方面，同时拥有ReturnsandParameters字段似乎不是很直观。例如，可以像这样编写文档

class MyVector:
    @properly
    def real(self):
        """Real part of the vector.

        Parameters
        ----------
        newreal : array-like
            New values to assign to the vector

        Returns
        -------
        real : MyVector
            Real part of the vector
        """
        pass

    @real.setter
    def real(self, newreal):
        pass

但是这样做会变得非常混乱，何时以及如何应用Parameters和/或Returns。Parameters例如，仅适用于 setter 并且Returns仅适用于 getter并不明显（至少对我而言） 。

有没有一种标准的方法可以很好地与 NumpyDoc 以及各种文档解析器（例如 Sphinx）一起使用？

Answer 1

以下napoleon 示例表明“标准”方式是记录getter,setter并且deleter在getter方法中，表明您这样做的方式是正确的。