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

Question

我一直在阅读Numpy 的文档标准，它似乎没有提到对象属性——只有类属性。

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

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.xml 中提供的How to Document文件中提到的内容。它提到类属性的文档应按如下方式处理。

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

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

它继续提到实例属性应该有自己的文档，并且只能按名称列出。

这是有道理的，但我在 numpy 源代码中找不到任何这样的例子。我发现的最接近的在ABCPolyBase 类中做了一些不同的事情。

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

在我看来，_polybase.py课程中使用的文档清晰易读，但我不相信该Class Attributes用法适用于 Sphinx 自动文档摘要。

我希望这些信息对你有用。