python - 有没有办法让类用 sphinx 继承其超类的文档？

Question

假设我有一堂课

class A(object):
  def myfunction():
    """A."""
    pass

和一个子类

class B(A):
  def myfunction():
    pass

是否可以使用 sphinx 从 A.myfunction 继承 B.myfunction 的 API 文档？B.myfunction 的文档应该是“A”。也是。

Answer 1

在python中，您可以通过在创建对象后分配给其“文档字符串”来设置对象的文档__doc__。最简洁的方法是使用复制父类的文档字符串的装饰器。您甚至可以为 提供额外的文档字符串B.myfunction，并将其附加到 的文档中A.myfunction（因为您可能正在专门研究它）。使用以下装饰器（改编自我对类似问题的回答），您可以复制覆盖函数的文档字符串，如下所示：

def copydoc(fromfunc, sep="\n"):
    """
    Decorator: Copy the docstring of `fromfunc`
    """
    def _decorator(func):
        sourcedoc = fromfunc.__doc__
        if func.__doc__ == None:
            func.__doc__ = sourcedoc
        else:
            func.__doc__ = sep.join([sourcedoc, func.__doc__])
        return func
    return _decorator

class A(object):
  def myfunction():
    """Documentation for A."""
    pass

class B(A):
  @copydoc(A.myfunction)
  def myfunction():
    """Extra details for B."""
    pass

结果：

>>> 帮助（B.myfunction）
关于模块 __main__ 中方法 myfunction 的帮助：

myfunction() 未绑定的 __main__.B 方法
    A 的文档。
    B的额外细节。

这需要明确说明您从哪里复制文档字符串：@copydoc(A.myfunction)。它可以说比全自动解决方案更灵活，因为您可以选择从哪里复制。

根据对这个问题的回答，我得出结论，一个干净、全自动的解决方案是不可能的：“函数只在运行时成为方法”，这个答案说，所以装饰器无法在函数中查找父类名称目的。你能做的最好的就是装饰师@copydoc(A)。这很容易，但是您不妨添加源方法的名称并保留灵活性。（如果您不同意，请发表评论，我将提供代码）。