来自父 class 的属性文档字符串未显示在使用 Sphinx 的内部 class 中

Question

我有一个 class 结构如下：

class BaseObject(IBaseObject):
    """
    DESCRIPTION 1
    """

    class Setup(TypedDict, total=False):
        """
        DESCRIPTION 1.1
        """
        log_id:IntKEY
        """DESCRIPTION 1.1.1"""
        name:str
        """DESCRIPTION 1.1.2"""

还有另一个 class 是这样的：

class VersionInfo(BaseObject):
    """
    DESCRIPTION 2

    """
    class Setup(BaseObject.Setup):
        items_dict:Dict[str,int]
        """DESCRIPTION 2.1.1"""
        hash:int
        """DESCRIPTION 2.1.2"""

当我创建文档时，我想在 VersionInfo.Setup 中看到 BaseObject.Setup 的属性（继承）中使用的 DESCRIPTION 1.1.1 和 1.1.2，但我只能查看没有描述的属性列表。

我尝试使用 :inherited-members: 但只添加了 TypedDict 功能。

编辑：class

class IBaseObject():
    @abstractmethod
    def setup(self, params:Optional[TypedDict]) -> None:
        raise NotImplementedError("Should implement setup method")

    @abstractmethod
    def InFields(self, filer:QSFiler) -> bool:
        raise NotImplementedError("Should implement setup method")

只是一个简单的 class，带有几个与嵌套 class Setup.

无关的抽象方法

IntKEY 只是一个 int 值

IntKEY = int

Answer 1

在这个解决方案中，从 dict 和 IBaseObject 的继承没有通过使用 :exclude-members: 选项显示，以免在视觉上使结果混乱。根据您的需要微调工作解决方案很容易。

下面是 classes 分组到一个代码围栏中（以方便复制粘贴）。 QSFiler 未在问题中定义，因此已更改为 int，但这是与问题中代码的唯一区别。我们假设它是一个名为 inner_class_problem.py 的模块，因为按名称引用需要 module/package 名称。

from abc import abstractmethod
from typing import TypedDict, Optional, Dict

IntKEY = int

class IBaseObject:

    @abstractmethod
    def setup(self, params: Optional[TypedDict]) -> None:
        raise NotImplementedError("Should implement setup method")

    @abstractmethod
    def InFields(self, filer: int) -> bool:
        raise NotImplementedError("Should implement setup method")

class BaseObject(IBaseObject):
    """
    DESCRIPTION 1
    """
    class Setup(TypedDict, total=False):
        """
        DESCRIPTION 1.1
        """
        log_id: IntKEY
        """DESCRIPTION 1.1.1"""
        name: str
        """DESCRIPTION 1.1.2"""

class VersionInfo(BaseObject):
    """
    DESCRIPTION 2

    """
    class Setup(BaseObject.Setup):
        items_dict: Dict[str, int]
        """DESCRIPTION 2.1.1"""
        hash: int
        """DESCRIPTION 2.1.2"""

对应的reStructuredText文件inner_class_problem.rst

inheritance with inner class
----------------------------

.. automodule:: inner_class_problem
    :members:
    :exclude-members: IBaseObject, BaseObject, VersionInfo

    .. autoclass:: IBaseObject
        :members:

    .. autoclass:: BaseObject
        :members:

    .. autoclass:: VersionInfo
        :members:
        :exclude-members: Setup

        .. autoclass:: inner_class_problem.VersionInfo::Setup
            :members:
            :inherited-members: dict
            :exclude-members: log_id, name

            .. autoattribute:: inner_class_problem.BaseObject::Setup.log_id
                :noindex:

            .. autoattribute:: inner_class_problem.BaseObject::Setup.name
                :noindex:

问题陈述是：内部 class VersionInfo.Setup 没有呈现记录继承变量 BaseObject.Setup.log_id 和 BaseObjectSetup.name.

的注释

为了避免这种情况，您可以成功地使用 :exclude-members: 选项隔离 VersionInfo.Setup 然后使用 .. autoattribute:: 指令包含继承变量 BaseObject.Setup.name 和 BaseObject.Setup.log_id 直接从父级 class 进入子级 class（使用了 :noindex: 选项 - 参见 Options and avanced usage- 以避免 Sphinx 发出重复警告）。

这很不方便，但它可能是您的最佳选择。有一些替代方案，比如直接在 .rst 文件 with domain declarations.

中编写 log_id 和 name 的文档

一般来说，来自父 classes 的成员的文档不会在子 classes 中重复，因为它只是重复。隐式继承的 class 签名告诉您继承的成员将记录在父 class.

中

来自父 class 的属性文档字符串未显示在使用 Sphinx 的内部 class 中

Attribute docstring from parent class isn't shown in inner class using Sphinx

python

inheritance

inner-classes

python-sphinx

autodoc