Question

当我使用Sphinx autodoc来记录一个类时，会始终报告属性的值（正如它所说的那样here，在＃437下），但始终为“= None”

Attribute = None
    Some Documentation

我把它包括在内

.. autoclass:: core.SomeClass
   :members:

我的代码看起来像

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

有没有办法让“=无”报告真实价值，或让它消失？

Answer 1

在即将发布的sphinx版本1.2（以及第二个测试版）中将会有一个:annotation:选项（请参阅pull-request）。

对于autodata / autoattribute，您可以强制使用特定值或禁止它。因此，为了不打印您要放置的属性的值：

.. autoclass:: core.SomeClass

   .. autoattribute:: attribute
      :annotation:

目前它只能直接与autodata / autoattribute一起使用，而不能与automodule / autoclass一起递归。

Answer 2

我很确定这与您的属性是实例属性这一事实有关。在实例化类之前，它不会获得值。 Sphinx导入模块以检查它们，但它不会实例化任何类。

因此Sphinx不知道“真实值”，并输出None。我认为你不能让它轻易消失（但我想如果你准备修补Sphinx源代码，任何事都有可能......）。如果你不喜欢这样，你可以在类的docstring中记录属性。

使用相同标记方案（described here）记录的类属性确实会在呈现的输出中显示它们的值。但是没有明确的迹象表明读者可以轻松区分类和实例属性。也许Sphinx在这里可能会更有帮助。

Answer 3

对于当前版本的Sphinx，您可以在项目的conf.py中放置一个monkeypatch来解决此问题：

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

这在Sphinx issue #2044

中讨论

Answer 4

这仍然是一个问题。我用它来解决这个问题：

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 =')

Answer 5

我无法获得针对实例属性的注释。我选择隐藏我主题中的属性值。

示例html

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

隐藏= None 的主题CSS

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

报告为“无”的属性的Sphinx值

5 个答案: