wartości Sphinx dla atrybutów zgłaszane jako Żaden

Question

Gdy używam Sphinx autodoktora udokumentować klasę, wartości atrybutów są zawsze podano, (jak to mówi, że powinien here pod # 437), ale zawsze jako „= None”

Attribute = None 
    Some Documentation 

I umieścić go jak

.. autoclass:: core.SomeClass 
    :members: 

A mój kod wygląda

class SomeClass(object): 
    def __init__(self): 
     self.attribute = "value" #: Some Documentation 

Czy istnieje sposób, aby uczynić raport "= Brak" prawdziwą wartością lub sprawić, by zniknął?

Answer 1

Jestem pewien, że ma to związek z tym, że atrybut jest atrybutem instancji. Nie dostaje wartości, dopóki klasa nie zostanie utworzona. Sphinx importuje moduły w celu ich sprawdzenia, ale nie tworzy instancji żadnych klas.

Tak więc "wartość rzeczywista" nie jest znana przez Sphinx, a wyjściowy jest None. Nie wydaje mi się, żebyś mógł łatwo odejść (ale przypuszczam, że wszystko jest możliwe, jeśli jesteś gotowy do poprawienia kodu źródłowego Sphinx ...). Jeśli ci się to nie podoba, możesz zamiast tego udokumentować atrybuty w docstringu klasy.

Atrybuty klasy, które są udokumentowane przy użyciu tego samego schematu znaczników (described here), otrzymują wyświetlane wartości w renderowanym wydruku. Ale nie ma wyraźnych wskazówek, które ułatwiają czytelnikowi rozróżnienie atrybutów klasy i instancji. Może Sphinx może być tu trochę bardziej pomocny.

Answer 2

Pojawi się opcja :annotation: (patrz pull-request) w nadchodzącej wersji 1.2 Sfinksa (oraz w drugiej wersji beta).

Dla autodata/autoattribute można następnie wymusić określoną wartość lub wyłączyć ją. Tak, aby wydrukować żadnej wartości dla atrybutu będzie można umieścić:

.. autoclass:: core.SomeClass 

    .. autoattribute:: attribute 
     :annotation: 

Obecnie działa tylko z autodata/autoattribute bezpośrednio i nie rekurencyjnie z automodule/autoclass.

Answer 3

To nadal wydaje się być problemem. Pracowałem wokół niego z:

class ValueDoc: 

    def __init__(self, text): 
     self.text = text 

    def __repr__(self): 
     return self.text 

a następnie zdefiniować atrybut na poziomie klasy jak:

#: documentation for foo 
foo = ValueDoc('text to show up after =') 

Answer 4

I nie był w stanie uzyskać adnotacje pracujących na przykład atrybuty. Zdecydowałem się po prostu ukryć wartości atrybutów w moim motywie.

Przykład html

<dl class="attribute"> 
    <dt> 
    <code class="descName">Attribute</code> 
    <em class="property"> = None</em> 
    </dt> 
</dl> 

Theme CSS ukryć = None

dd dl.attribute em.property { display: none } 

Answer 5

Dla bieżącej wersji Sphinx, można umieścić monkeypatch w conf.py swojego projektu, który rozwiązuje ten problem:

from sphinx.ext.autodoc import (
    ClassLevelDocumenter, InstanceAttributeDocumenter) 

def iad_add_directive_header(self, sig): 
    ClassLevelDocumenter.add_directive_header(self, sig) 

InstanceAttributeDocumenter.add_directive_header = iad_add_directive_header 

Jest to omówione w Sphinx issue #2044