属性的 Sphinx 值报告为无答案

【问题标题】：Sphinx values for attributes reported as None属性的 Sphinx 值报告为无
【发布时间】：2012-02-05 22:04:56
【问题描述】：

当我使用 Sphinx 自动文档记录一个类时，属性的值总是被报告，（正如它所说的应该 here，在 #437 下）但总是作为“= None”

Attribute = None
    Some Documentation

我喜欢包含它

.. autoclass:: core.SomeClass
   :members:

我的代码看起来像

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

有没有办法让“= None”报告真正的价值，或者让它消失？

【问题讨论】：

你在哪里看到= None？
这里，例如：readthedocs.org/docs/domination-game/en/latest/…。它出现在我将self.attribute = ... 与autoclass:: .. :members:结合使用的任何地方

标签： python python-sphinx autodoc

【解决方案1】：

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

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

.. autoclass:: core.SomeClass

   .. autoattribute:: attribute
      :annotation:

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

【讨论】：

这似乎只适用于类属性。使用 Sphinx 1.5.1 测试

【解决方案2】：

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

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

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

【讨论】：

我不认为这个答案的工作假设是正确的。我遇到了在 __init__() 函数之外定义和初始化的类属性的问题（即 - “ = None”出现在生成的文档中）。这些都记录在案，使用放置在同一行的属性之后的“#: ...”注释变体。
有趣。你有 GitHub 项目或类似的项目吗？
是的：github.com/capn-freako/PyBERT/blob/…
查看 PyBERT 类的属性，例如 bit_rate。请注意，此版本中的 cmets 尚不正确。（他们在井号后缺少冒号。）我正在使用更正的 cmets，在我自己的沙箱中，尚未推送。
好的，会的。谢谢你的时间！节日快乐。 :)

【解决方案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

这在Sphinx issue #2044中讨论

【讨论】：

【解决方案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 =')

【讨论】：

【解决方案5】：

我无法获得适用于实例属性的注释。我选择在我的主题中隐藏属性值。

示例 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 }

【讨论】：

您可以尝试一个名为autoinstanceattribute 的未记录指令。目前尚不清楚该指令是否只需要记录在案，或者autoattribute 是否真的应该也处理实例属性。见github.com/sphinx-doc/sphinx/issues/904#issuecomment-68577602。
所以带有空白:annotation: 选项的.. autoinstanceattribute 指令确实成功带走了值！看来这个实现在 1.5 中有点乱。