Python-Sphinx：从超类“继承”方法文档

Question

编辑：截至目前（Sphinx 1.4.9），似乎无法告诉 Sphinx 做我想做的事（请参阅 GitHub 上的问题）。 Brecht Machiels 的公认答案以另一种方式解决了这个问题，直到 Sphinx 有一天能够做到这一点。

描述：我正在尝试使用 sphinx-apidoc 记录一个 Python 项目。 Sphinx 配置几乎是默认的，我只是包含了'sphinx.ext.autodoc' 。

它一般工作，但派生类不会像我期望的那样继承其超类的方法文档。

示例：考虑一个名为project的非常简约的 Python 包。 除了一个空的__init__.py它只包含一个文件（ base.py ，见下文）

# -*- coding: utf-8 -*
import abc


class Superclass(object):
    """The one to rule them all"""

    @abc.abstractmethod
    def give(self, ring):
        """Give out a ring"""
        pass


class Derived(Superclass):
    """Somebody has to do the work"""

    def give(self, ring):
        print("I pass the ring {} to you".format(ring))

运行 sphinx-apidoc ( sphinx-apidoc -o apidoc project -f ) 生成以下文件：

• apidoc/modules.rst

   project ======= .. toctree:: :maxdepth: 4 project

• apidoc/project.rst

   project package =============== Submodules ---------- project.base module ------------------- .. automodule:: project.base :members: :undoc-members: :show-inheritance: Module contents --------------- .. automodule:: project :members: :undoc-members: :show-inheritance:

在默认的index.rst包含apidoc/modules.rst后跟make html为类及其方法生成基本的 html 文档。 不幸的是， Derived.give的文档字符串是空的。

问题：有没有办法告诉 Sphinx 在没有装饰器魔法的情况下获取父级的方法文档，如这篇SO 帖子中所述，对于每个方法？

Answer 1

您可以通过为抽象基类使用元类来自动管理文档字符串。 下面是这种元类的一个非常基本的实现。 它需要扩展以正确处理多个基类和极端情况。

# -*- coding: utf-8 -*
import abc


class SuperclassMeta(type):
    def __new__(mcls, classname, bases, cls_dict):
        cls = super().__new__(mcls, classname, bases, cls_dict)
        for name, member in cls_dict.items():
            if not getattr(member, '__doc__'):
                member.__doc__ = getattr(bases[-1], name).__doc__
        return cls


class Superclass(object, metaclass=SuperclassMeta):
    """The one to rule them all"""

    @abc.abstractmethod
    def give(self, ring):
        """Give out a ring"""
        pass


class Derived(Superclass):
    """Somebody has to do the work"""

    def give(self, ring):
        print("I pass the ring {} to you".format(ring))

这甚至是比让 Sphinx 这样做更好的解决方案，因为在派生类上调用help()时，这也将起作用。