如何使用 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

下面的napoleonexample表示“标准”方式是将getter、setter和deleter记录在getter方法中，说明你的做法是正确。