有没有办法让类继承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__在创建对象的"docstring" 之后设置它来设置对象的文档.最简单的方法是使用复制父类的docstring的装饰器.您甚至可以为其提供额外的文档字符串B.myfunction,并将其附加到文档中A.myfunction(因为您可能会将其专门化).使用以下装饰器(根据我对类似问题的回答改编),您可以复制被覆盖函数的docstring,如下所示:

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

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