如何在Sphinx文档中显示实例属性？

Question

有没有自动显示变量var1和var2及其初始值在Sphinx文档中的方法？

class MyClass:
    """    
    Description for class
    """

    def __init__(self, par1, par2):
       self.var1 = par1 * 2
       self.var2 = par2 * 2

    def method(self):
       pass

- Meloun

Answer 1

你的变量是实例变量，而不是类变量。

如果没有将文档字符串（或#:“文档注释”）附加到变量上，则它们将不会被记录。你可以按照以下方式操作：

class MyClass(object):
    """    
    Description for class 

    """

    def __init__(self, par1, par2):
        self.var1 = par1 #: initial value: par1
        self.var2 = par2 #: initial value: par2

    def method(self):
        pass

但是我更喜欢使用信息域来包含变量文档：

class MyClass(object):
    """    
    Description for class

    :ivar var1: initial value: par1
    :ivar var2: initial value: par2
    """

    def __init__(self, par1, par2):
        self.var1 = par1 
        self.var2 = par2 

    def method(self):
        pass

另请参见:

• http://www.sphinx-doc.org/ext/autodoc.html#directive-autoattribute
• 如何使Python/Sphinx仅记录在__init__中声明的对象属性？
• 使用autodoc时遇到明确定义的实例属性问题

- mzjn

---

需要为 #: doc comment 在 Sphinx 生成的 HTML 页面中可见做任何设置吗？我使用 sphinx-apidoc 命令生成了 .rst 文件。 - varunsinghal

@varunsinghal：有问题吗？ - mzjn

我使用这些文档注释#: 来描述私有类变量。 - varunsinghal

@varunsinghal：也许你遇到了这个 bug？https://github.com/sphinx-doc/sphinx/issues/1362 - mzjn

好的回答！你不必使用 :ivar foo:，只需要用 :var foo 就可以了。 - RayLuo

@RayLuo，它们并不是同义词 - ivar表示实例变量，cvar表示类变量，而var则需要自己理解。虽然Sphinx不关心这些，但它会告知人类读者。 - c z

Answer 2

针对 Python 3.9+ 的 dataclass 风格类，您可以这样做：

@dataclass
class MyClass:

    #: Nice vars!
    var1: int = 0

    #: Life is beautiful, remember to buy flowers for your wife
    var2: int = 0

这里是一个使用dataclass的Sphinx文档示例链接。

- Mikko Ohtamaa

---

这些实际上是类（静态）变量，而不是数据类字段。要成为数据类字段，您需要对它们进行注释，例如 var1: int = 0。 - rv.kvetch

Answer 3

文档注释：你也可以将文档注释放在上面

除了使用 self.var1 = par1＃var1的文档 语法之外，您还可以：

main.py

class MyOtherClass:
    """
    This class does that.
    """
    pass

class MyClass:
    """
    Description for class.
    """

    #: Syntax also works for class variables.
    class_var: int = 1

    def __init__(self, par1: int, par2: MyOtherClass):
        #: Doc for var1
        self.var1: int = par1

        #: Doc for var2.
        #: Another line!
        self.var2: MyOtherClass = par2

    def method(self):
        """
        My favorite method.
        """
        pass

    @classmethod
    def cmethod():
        """
        My favorite class method.
        """
        pass

build.sh

sphinx-build . out

conf.py

import os
import sys
sys.path.insert(0, os.path.abspath('.'))
extensions = [ 'sphinx.ext.autodoc' ]
autodoc_default_options = {
    'members': True,
}
autodoc_typehints = "description"

index.rst

.. automodule:: main

requirements.txt

Sphinx==6.1.3

在运行./build.sh之后，out/index.html下的输出如下：

#: 语法的文档在此处：https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-autoproperty

改用 :ivar: 和:cvar:

目前两种方法之间存在权衡，可惜没有一种明显优越的方法。

缺点：

• 你必须重新输入属性名称
• 类型已经消失，待办：链接特性请求

优点：

• "Variables:` 分组看起来更整洁，待办：链接特性请求

两种方法都可以更好：

• 清楚地显示 class_var 是类变量？待办：链接特性请求

class MyClass:
    """
    Description for class.

    :ivar var1: Doc for var1
    :ivar var2: Doc for var2.
      Another line!
    :cvar class_var: Syntax also works for class variables.
    """

    class_var: int

    def __init__(self, par1: int, par2: MyOtherClass):
        self.var1: int = par1

        self.var2: MyOtherClass = par2

    def method(self):
        """
        My favorite method.
        """
        pass

    @classmethod
    def cmethod():
        """
        My favorite class method.
        """
        pass

产生：

相关：Python Sphinx中var、cvar和ivar的区别是什么？

在Python 3.10、Ubuntu 22.10上进行了测试。

- Ciro Santilli OurBigBook.com