使用Sphinx的内部类中未显示父类的属性docstring

Question

我的课程结构如下：

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"""

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

我尝试使用:inherited-members:，但只添加了TypedDict函数

编辑：课堂

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")

只是一个简单的类，有几个与嵌套类Setup无关的抽象方法

IntKEY只是一个int值

IntKEY = int

Answer 1

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

下面是分组到单个代码栏中的类（以便于复制粘贴）QSFiler没有在问题中定义，因此它被更改为int，但这是与问题中代码的唯一区别。让我们假设它是一个名为inner_class_problem.py的模块，因为按名称引用需要模块/包名称

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"""

相应的重构文本文件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:

问题陈述是：内部类VersionInfo.Setup没有呈现记录内部变量BaseObject.Setup.log_id和BaseObjectSetup.name的注释

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

这很不方便，但可能是你最好的选择。有一些替代方法，比如直接在.rst文件with domain declarations中编写log_id和name的文档

通常，父类成员的文档不会在子类中重复，因为它只是重复。继承的类签名隐式地告诉您继承的成员将记录在父类中