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

Question

我正在管理一个使用 NumpyDoc 风格的包，我正在尝试正确记录某些属性的 setter/getter。

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

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 example表示“标准”方法是在 getter 方法中记录 getter、setter 和 deleter，说明你的做法是正确的。