Как я должен документировать атрибуты класса и объекта, используя стиль Numpy?

Я читал Стандарты документации 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

EDIT: Просто хочу отметить, что я перехожу на Napoleon, в котором говорится, что он поддерживает атрибуты, но не специфические атрибуты класса или экземпляра.

Ответы

Ответ 1

Я попробовал то, что упоминается в файле Документ, предоставленном в numpy. В нем упоминается, что документация атрибутов класса должна обрабатываться следующим образом.

Раздел "Атрибуты", расположенный ниже раздела "Параметры", может использоваться для описания переменных класса:

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.

Я надеюсь, что эта информация будет полезна.