Значения сфинкса для атрибутов, указанных как None

Question

Когда я использую автодок Sphinx для документирования класса, всегда сообщается о значениях атрибутов (как говорится, здесь , под # 437), но всегда как "= Нет"

Attribute = None
    Some Documentation

Я включаю это как

.. autoclass:: core.SomeClass
   :members:

И мой код выглядит как

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

Есть ли способ сделать так, чтобы "= None" сообщал реальное значение, или чтобы оно исчезло?

Answer 1

Будет опция :annotation: (см. pull-request ) в следующей версии 1.2 сфинкса (и во второй бете).

Для autodata / autoattribute вы можете затем принудительно задать конкретное значение или подавить его. Таким образом, чтобы вывести значение атрибута, вы не должны указывать:

.. autoclass:: core.SomeClass

   .. autoattribute:: attribute
      :annotation:

В настоящее время он работает только с autodata / autoattribute напрямую, а не рекурсивно с automodule / autoclass.

Answer 2

Я почти уверен, что это связано с тем фактом, что ваш атрибут является атрибутом экземпляра.Он не получает значение, пока не создан экземпляр класса.Sphinx импортирует модули для проверки их, но не создает экземпляры каких-либо классов.

Таким образом, «действительное значение» не известно Sphinx, и выводится None.Я не думаю, что вы можете сделать это легко (но я полагаю, что все возможно, если вы готовы исправлять исходный код Sphinx ...).Если вам это не нравится, вместо этого вы можете задокументировать атрибуты в строке документации класса.

Атрибуты класса, которые задокументированы с использованием той же схемы разметки ( описанная здесь ), получают свои значенияотображается в отрендеренном выводе.Но нет четкого указания, позволяющего читателю легко различать атрибуты класса и экземпляра.Возможно, Сфинкс мог бы быть немного более полезным здесь.

Answer 3

Для текущей версии Sphinx, вы можете поместить обезьяну-патч в conf.py вашего проекта, который решает эту проблему:

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

Это обсуждается в выпуске Сфинкса # 2044

Answer 4

Мне не удалось заставить работать аннотации для атрибутов экземпляра.Я решил просто скрыть значения атрибутов в моей теме.

Пример HTML

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

Тема CSS для сокрытия = None

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

Answer 5

Это все еще кажется проблемой.Я обошел это с:

class ValueDoc:

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

    def __repr__(self):
        return self.text

А затем определил атрибут на уровне класса как:

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