我应该如何使用Numpy的样式记录类和对象属性？

Question

我一直在阅读Numpy's documentation standards，它似乎没有提到对象属性 - 只有类属性。

那么，例如，我将如何记录以下内容？

class ClassA(object):
    """Short description of ClassA

    Long description of ClassA

    Parameters
    ----------
    param : param_type, optional
        param_description

    Attributes (class)
    ----------
    class_attr : class_attr_type
        class_attr_description

    Attributes (object)
    ----------
    obj_attr : obj_attr_type
        obj_attr_description

    """

    class_attr = 'something'

    def __init__(self, arg='something else'):
        self.obj_attr = arg

编辑： 只是想注意我正在切换到Napoleon，它表示它支持属性，但不是特定的类或实例属性。

Answer 1

我尝试了numpy中提供的How to Document文件中提到的内容。它提到类属性的文档应该按如下方式处理。

  

属性部分位于“参数”部分下方，可用于描述类变量：

Attributes
----------
x : float
    The X coordinate.
y : float
    The Y coordinate.

接着提到实例属性应该有自己的文档，只能按名称列出。

这是有道理的但我在numpy源代码中找不到任何这样的例子。我发现的最接近ABCPolyBase class的内容有所不同。

Attributes
----------
coef : (N,) ndarray 
...
Class Attributes
----------------
maxpower : int

在我看来，_polybase.py类中使用的文档清晰可辨，但我认为Class Attributes用法不适用于Sphinx autodoc摘要。

我希望这些信息有用。