Sphinx属性值报告为None

Question

当我使用Sphinx的自动文档功能来记录一个类的时候，属性的值总是被报告出来，(正如它在这里所说的，编号为#437)，但总是显示为“= None”。

Attribute = None
    Some Documentation

我这样包含它：

.. autoclass:: core.SomeClass
   :members:

而我的代码看起来是这样的：

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

有没有办法让“= None”显示真实的值，或者让它消失呢？

Answer 1

对于当前版本的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的第2044号问题中有讨论。

Answer 2

在即将发布的sphinx 1.2版本（还有第二个测试版）中，会有一个:annotation:选项（具体可以查看这个链接）。

对于autodata和autoattribute，你可以强制指定一个特定的值，或者选择不显示这个值。也就是说，如果你想让某个属性不显示任何值，你可以这样写：

.. autoclass:: core.SomeClass

   .. autoattribute:: attribute
      :annotation:

目前这个功能只适用于autodata和autoattribute，不能在automodule和autoclass中递归使用。

Answer 3

我觉得这跟你的属性是实例属性有关。实例属性在类被创建之前是没有值的。Sphinx是用来检查模块的，但它并不会创建任何类的实例。

所以，Sphinx不知道“真实的值”，因此输出的是None。我觉得想要解决这个问题并不简单（不过如果你愿意修改Sphinx的源代码，什么都有可能...）。如果你不喜欢这种情况，可以考虑在类的文档字符串里描述这些属性。

使用相同的标记方式来记录的类属性（在这里描述）会在最终输出中显示它们的值。但没有明确的标识让读者容易区分类属性和实例属性。也许Sphinx在这方面可以更友好一些。