有没有一种方法可以让类继承它们的超类的文档?

2022-04-20 00:00:00 python python-sphinx

问题描述

假设我有一个类

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

和一个子类

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

是否可以通过Shinx从A.myFunction继承B.myFunction的接口文档?B.myFunction的文档应该是"A"。我也是。


解决方案

在Python中,您可以通过在对象创建后将其赋值给它的"文档字符串"__doc__来设置对象的文档。要做到这一点,最简单的方法是使用一个复制父类的文档字符串的修饰符。您甚至可以为B.myfunction提供额外的文档字符串,并将其附加到A.myfunction的文档中(因为您可能将其专门化)。使用以下修饰符(改编自my answer类似的问题),您可以复制被覆盖函数的文档字符串,如下所示:

def copydoc(fromfunc, sep="
"):
    """
    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 question的回答,我得出结论,一个干净的、全自动的解决方案是不可能的:this answer,说:"函数只在运行时变成方法",因此装饰者无法在Function对象中查找父类名称。您最多只能做一个装饰师@copydoc(A)。这很容易,但是您也可以添加源方法的名称并保留其灵活性。(如果您不同意,请发表意见,我将提供代码)。

相关文章