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

51 投票

2 回答

38742 浏览

提问于 2025-04-17 09:05

有没有什么方法可以在sphinx文档中自动显示变量var1和var2及其初始值呢？

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

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

    def method(self):
       pass

文档生成实例属性 sphinx 自动化文档

2 个回答

#: 文档注释：你也可以把文档注释放在变量的上面

除了使用 self.var1 = par1 # Doc for 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: 替代

目前这两种方法各有利弊，真可惜没有一种方法是绝对优越的。

缺点：

你需要再次输入属性名称
类型信息消失了，TODO 需要链接到功能请求

优点：

变量分组看起来更整洁，TODO 需要链接到功能请求

这两种方法都可以改进：

能否清楚地显示 class_var 是一个类变量？TODO 需要链接到功能请求

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 3.10 和 Ubuntu 22.10 上测试过。

回答于 2025-04-17 由 Python大师

分享举报

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

如果不在变量旁边加上文档字符串（或者用#:的方式写“文档注释”），这些变量就不会被记录下来。你可以这样做：

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

另外，参考一下：

回答于 2025-04-17 由 Python大师

分享举报

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

2 个回答

撰写回答