如何使用 NumpyDoc 正确记录属性

Question

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

特别是，python 忽略了 setter 的文档，因此我遇到了一个问题，因此所有文档都必须进入 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 and/or Returns 何时以及如何适用变得非常混乱。例如。 Parameters 仅适用于 setter 并且 Returns 仅适用于 getter.

并不明显（至少对我而言）

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

Answer 1

下面的napoleonexample表示"standard"的方式是将getter、setter和deleter的文件记录在getter方法，说明你的做法是正确的。

如何使用 NumpyDoc 正确记录属性

How to properly document properties with NumpyDoc

python

code-documentation

numpydoc