Sphinx是否应该能够在类中记录实例属性？

Question

我发现有冲突且经常过时的信息，以便希望有人可以解决此问题。

我想使用Sphinx记录如下内容：

class MyClass:
    """
    MyClass, which is documented with a docstring at the class level
    """
    classVar = None
    """A class var with an initial value and a 1-line doc"""

    def __init__(self):
        """
        __init__'s docs
        """
        instanceVar1 = 10
        """An instance var with an initial val and 1-line doc"""

        #: An instance var with an initial val and a doc-comment
        instanceVar2 = 10

在我的文档中，我想查看instanceVar1及其文档字符串（理想情况下是其默认值，但我只对描述感到满意）。但是，如果我运行的第一个文件为：

.. automodule:: mymodule.mycode
   :members:

我只看到类属性，而不是实例属性：

Google搜索功能使我在应该/不应该使用的内容上出现冲突的信息。几个较早的堆栈溢出链引用了实例属性的自动文档化问题（例如here），但如果您像我在上文中一样添加了文档字符串，它们也会引用自动文档化的问题。 Sphinx文档引用了all attributes can be autodocumented。

任何人都可以评论我现在想做的事情是否应该对您有用/对我有用吗？谢谢。

Answer 1

是的，您所做的应该起作用，并且它最终为我工作。

为了演示，我使用的是您引用的Sphinx文档中的示例：

class Foo:
    """Docstring for class Foo."""

    #: Doc comment for class attribute Foo.bar.
    #: It can have multiple lines.
    bar = 1

    flox = 1.5   #: Doc comment for Foo.flox. One line only.

    baz = 2
    """Docstring for class attribute Foo.baz."""

    def __init__(self):
        #: Doc comment for instance attribute qux.
        self.qux = 3

        self.spam = 4
        """Docstring for instance attribute spam."""

我将其另存为module.py，并创建了以下index.rst：

.. automodule:: module

与此Sphinx配置文件conf.py一起：

import sys
sys.path.insert(0, '.')
extensions = ['sphinx.ext.autodoc']
autodoc_default_options = {
    'members':         True,
    'member-order':    'bysource',
    'special-members': '__init__',
}

将所有三个文件存储在同一文件夹中，我通过sphinx-build . ./html（在Python 3.7.3和Windows 10上）运行Sphinx（2.1.1），以将其呈现为HTML：

关于您“可能已经搞砸了”的内容……嗯，这已经足够了，因为我敢肯定您会同意的。 ;-)起初，我尝试了与上面相同的尝试，但是花了您提供的代码示例，我花了相当长的时间才意识到：您的两个所谓的实例属性instanceVar1和instanceVar2，前面缺少self标识符。哎呀。这就是为什么它不起作用。