为什么 Sphinx 不显示继承的成员？

Question

我有一个基础 class Base 和一个衍生 class Derived。使用 Sphinx，我希望 Base 的 class 属性出现在 Derived 的文档中；我以为 :inherited-members: 可以解决问题，但到目前为止我运气不好。

请注意，与不同，我需要记录的成员不会在 class 中硬编码，仅在 class 文档字符串中出现。

最小工作示例：在 tmp/ 下，我有文件 a.py:

class Base:
    """
    :param x: X
    :type x: int
    """
    x = 1


class Derived(Base):
    """
    :param y: Y
    :type y: int
    """
    y = 2

文件index.rst:

Tmp
===

.. autoclass:: tmp.a.Base
    :members:

.. autoclass:: tmp.a.Derived
    :show-inheritance:
    :inherited-members:
    :members:

和conf.py，其中只包含extensions = ['sphinx.ext.autodoc']。如果我运行命令

python -m sphinx.cmd.build . ./tmphtml/

然后输出 tmphtml/index.html 显示：

如何让 x 出现在 Derived 的 Parameters 部分下？我当前的 Sphinx 版本是 3.3.1.

Answer 1

我认为这可能是 Sphinx 中的错误，但您的示例中也有错误。

您的错误是没有正确记录 x 或 y class 属性。 :param: 角色用于描述函数参数，因此 Sphinx 不会将 x 和 y 参数与同名的 class 属性相关联。然后，由于 Sphinx 认为 class 属性未记录，因此不会将它们包含在文档中。以下是应如何记录属性：

class Base:
    x = 1
    """Spam"""

class Derived(Base):
    y = 2
    """Eggs"""

（可能的）错误是，即使您这样做，Sphinx 仍然认为属性未记录。我认为这可能是属性没有真正的文档字符串的结果，这迫使 Sphinx 在幕后做一些技巧以使其看起来像它们一样，但我不太确定。在任何情况下，您都可以通过在 .. autoclass:: 指令中包含 :undoc-members: 来解决此问题。这当然会包括文档中所有未记录的 method/attribute，但我想不出解决这个问题的方法。

另一个值得一提的替代方案是我编写的名为 autoclasstoc 的插件。这基本上是让 Derived 的文档包含 x 和 y 的文档链接的简单方法。 y 文档实际上位于同一页面上，因为它是 Derived class 的一部分，而 x 文档位于 Base 页面上。每个方法（包括继承的方法）也都有组织良好的链接。这并不能完全回答你的问题，但我认为它有同样的想法。

为什么 Sphinx 不显示继承的成员？

Why isn't Sphinx showing inherited members?

python

python-sphinx

autodoc