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

Question

我通读了 Numpy's documentation standards，它似乎没有提到对象属性——只有 class 属性。

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

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，它说它支持属性，但不是特别支持 class 或实例属性。

Answer 1

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

An Attributes section, located below the Parameters section, may be used to describe class variables:
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 中使用的文档清晰易读，但我认为 Class Attributes 的用法不适用于 Sphinx autodoc 摘要。

希望这些信息对您有所帮助。

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

How should I document class and object attributes using Numpy's style?

python

numpy

scipy

python-sphinx

sphinx-napoleon