autodoc和明确指定的实例属性存在的问题

Question

我编写了一个python类，并使用sphinx编写了文档。例如，该类如下所示：

class Aclass(object):
    """ my class """

    def __init__(self):
        """ constructor """

        self.a = None
        """ doc for attribute a """

        self._prop = None

    def _get_prop(self):
        """ getter prop """
        return self._prop

    def _set_prop(self, val):
        """ setter prop """
        self._prop = val

    prop = property(_get_prop, _set_prop)
    """ a property """

    def square(self):
        """ return square of a """
        return self.a**2

现在，为了做文档，在我写的第一个文件中：

.. autoclass:: aclass.Aclass
   :members:

一切正常，并且a，prop和square出现在文档中。

<< img src =“ https://image.soinside.com/eyJ1cmwiOiAiaHR0cHM6Ly9pLnN0YWNrLmltZ3VyLmNvbS9hbzdzbi5wbmcifQ==” alt =“在此处输入图像描述”>

但是，如果我尝试分别记录属性和方法，sphinx说它无法找到属性a，但适用于prop。

.. autoattribute:: aclass.Aclass.prop

.. autoattribute:: aclass.Aclass.a

错误消息是：

Traceback (most recent call last):                                                                                
  File "/usr/lib/python2.7/dist-packages/sphinx/ext/autodoc.py", line 326, in import_object
    obj = self.get_attr(obj, part)
  File "/usr/lib/python2.7/dist-packages/sphinx/ext/autodoc.py", line 232, in get_attr
    return safe_getattr(obj, name, *defargs)
  File "/usr/lib/python2.7/dist-packages/sphinx/util/inspect.py", line 70, in safe_getattr
    raise AttributeError(name)
AttributeError: a

/home/gvallver/dev/sphinx/doc/source/index.rst:17: WARNING: autodoc can't import/find attribute 'aclass.Aclass.a', it reported error: "a", please check your spelling and sys.path

[我在Sphinx values for attributes reported as None的某个地方读到，狮身人面像没有使该类实例化，因此类属性（作为prop）与实例属性（作为a）之间存在差异。但是我如何在文档中引用实例属性？

实际上，如果在第一个文件中未明确询问实例属性，则会找到它们。例如，这将起作用：

.. autoclass:: aclass.Aclass
    :members:

但是这不

.. autoclass: aclass.Aclass
    :members: a

Answer 1

有关于此的错误报告（创建于2012-03-30；仍于2015-12-12开放：： https://github.com/sphinx-doc/sphinx/issues/904。

1. 包含实例属性的显式:members:列表的问题已在this commit中修复（包含在Sphinx 1.2b1中）。

2. 如评论中所提到（乔恩·沃尔特曼（Jon Waltman）所述，有一个未记录的autoinstanceattribute指令。

   使用.. autoinstanceattribute:: aclass.Aclass.a确实有效（使用Sphinx 1.1.3和1.2b1测试）。