有没有办法让类用 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 的文档中（因为您可能正在专门研究它）。使用以下装饰器（改编自 my answer 到类似问题），您可以像这样复制覆盖函数的文档字符串：

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)。它可以说比全自动解决方案更灵活，因为您可以选择从哪里复制。

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