时间戳

首页 > 解决方案 > Sphinx 是否应该能够记录类中的实例属性？

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

问题描述

我发现相互矛盾且经常过时的信息，因此希望有人能澄清这一点。

我想用 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:

我只看到类属性，而不是实例属性： 显示文档的图像

谷歌搜索给了我关于什么应该/不应该工作的相互矛盾的信息。几个较旧的堆栈溢出链引用了实例属性的自动文档问题（例如此处），但如果您像我上面所做的那样添加了文档字符串，它们也会引用它。Sphinx 文档引用所有属性都可以自动记录。

任何人都可以评论我正在尝试做的事情是否应该工作/现在对他们有用/你/建议我可能搞砸了什么？谢谢。

标签： pythonpython-sphinxautodoc

解决方案

是的，你所做的应该奏效，而且它——最终——对我有用。

为了演示，我使用了您引用的 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： 呈现的 HTML

至于你“可能搞砸了什么”……嗯，说得够充分，我相信你会同意的。;-) 我花了很长时间才意识到这一点，起初，我尝试了与上面相同的方法，但是使用您提供的代码示例：您的两个所谓的实例属性instanceVar1和instanceVar2, 缺少self前面的标识符。哎呀。这就是为什么它不起作用。

推荐阅读