有没有一种方法可以让类继承它们的超类的文档？ [英] Is there a way to let classes inherit the documentation of their superclass with 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)。这很容易，但是您也可以添加源方法的名称并保留其灵活性。(如果您不同意，请发表意见，我将提供代码)。

这篇关于有没有一种方法可以让类继承它们的超类的文档？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！