Jak powinienem dokumentować atrybuty klas i obiektów za pomocą stylu Numpy?

Question

Czytałem przez Numpy's documentation standards, i nie wydaje się, aby wspomnieć o atrybutach obiektu - tylko atrybuty klasy.

Na przykład, w jaki sposób mogę udokumentować następujące?

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: Chciałem tylko zwrócić uwagę, że jestem przełączania Napoleon, które mówi, że obsługuje atrybuty, ale nie specjalnie instancja klasy lub atrybuty.

Answer 1

Próbowałem tego, co jest wymienione w pliku How to Document podanym w numpy. Wymienia dokumentację atrybutów klasowych, które należy traktować w następujący sposób.

odcinek znajdujący się poniżej sekcji Parametry Atrybuty mogą być wykorzystane do opisania zmiennych klasy:

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

To idzie na wspomnieć, że właściwości instancji powinien mieć swoją własną dokumentację i być wymienione tylko wg nazwy.

To ma sens, ale nie mogę znaleźć żadnych przykładów tego w numpy kodu źródłowego. Najbliższe, które znalazłem, zrobiły coś innego w ABCPolyBase class.

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

Moim zdaniem, dokumentacja wykorzystywane w klasie _polybase.py jest czytelne, ale nie wierzę, korzystanie Class Attributes będzie współpracować z Sphinx podsumowań AutoDoc.

Mam nadzieję, że ta informacja jest przydatna.