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__后指定它来设置对象的文档。最简单的方法是使用复制父类的docstring的装饰器。您甚至可以为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

结果：

>>> help(B.myfunction)
Help on method myfunction in module __main__:

myfunction() unbound __main__.B method
    Documentation for A.
    Extra details for B.

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

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

有没有办法让类继承sphinx的超类文档？

1 个答案: