Jak mogę wygenerować dokumentację dla setera właściwości Pythona za pomocą Sphinx?

Question

Mam klasy Python coś jak poniżej, z docstrings mają być przekształcone w dokumentacji przez Sphinx:

class Direction(object): 
    """ 
    A direction in which movement can be made. 
    """ 
    def __init__(self): 
     self._name = None 

    @property 
    def name(self): 
     """ 
     The unique name of the direction. 

     :return: The direction name 
     :rtype: string 
     """ 
     return self._name 

    @name.setter 
    def name(self, value): 
     """ 
     Sets the direction name. 

     :param string value: The direction name 
     """ 
     self._name = value 

Wyjście Sphinx wygląda mniej więcej tak:

klasyDirection (name) Kierunek, w którym można wykonać ruch.

nazwa Unikalna nazwa kierunku.

Powroty: Z nazwą kierunek

typ Powrót: ciąg

co jest w porządku, jak dalece jak to jest, ale należy pamiętać, kompletny brak jakiejkolwiek informacji o setera name.

Czy istnieje sposób, aby Sphinx wygenerował dokumentację dla właściciela nieruchomości?

Answer 1

Sphinx ignoruje docstrukcje na ustawieniach właściwości, więc cała dokumentacja dla danej nieruchomości musi być zgodna z metodą @property.

Podczas gdy Sphinx rozumie określone znaczniki (np. :param ...:), akceptuje wszystkie niestandardowe znaczniki i renderuje je jako etykiety dla tekstu, który za nimi podąża.

Dlatego coś jak poniżej będą wykonywali dokumentację w rozsądny sposób (getter, setter i type można zmienić na dowolny inny tekst w razie potrzeby).

@property 
def name(self): 
    """ 
    The unique name of the direction. 

    :getter: Returns this direction's name 
    :setter: Sets this direction's name 
    :type: string 
    """ 
    return self._name 

Wytworzona dokumentacja wygląda mniej więcej tak:

klasyDirection (nazwa) kierunku, w którym można wykonać ruch.

nazwa Unikalna nazwa kierunku.

Getter: Zwraca nazwę ten kierunek za

Seter: Zestawy nazwa tym kierunku za

Typ: ciąg

T hanks do @BrenBarm i @ A-B-B za skierowanie mnie w kierunku tego rozwiązania.