关于python：有没有办法让类继承sphinx的超类文档？


Is there a way to let classes inherit the documentation of their superclass with sphinx?

假设我有个班

1
2
3
4
class A(object):
  def myfunction():
   """A."""
    pass

和一个子类

1
2
3
class B(A):
  def myfunction():
    pass

号

是否可以从带有sphinx的a.myFunction继承b.myFunction的api文档？b.myfunction的文档也应该是"a"。

在python中，可以通过在对象创建后分配给它的"docstring"__doc__来设置对象的文档。最干净的方法是使用一个复制父类的docstring的装饰器。您甚至可以为B.myfunction提供一个附加的docstring，并将其附加到A.myfunction的文档中(因为您可能正在专门化它)。使用以下修饰符(根据我对类似问题的回答改编)，您可以像这样复制被重写函数的docstring：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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

结果：

1
2
3
4
5
6
>>> help(B.myfunction)
Help on method myfunction in module __main__:

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

号

这需要明确地说明从哪里复制docstring:@copydoc(A.myfunction)。可以说，它比全自动解决方案更灵活，因为您可以选择从何处复制。

基于这个问题的答案，我得出结论，一个干净的、完全自动的解决方案是不可能的："函数只在运行时成为方法"，这个答案说，所以装饰器无法在函数对象中查找父类名称。你能做的最好的事情就是找一个装饰工。这很容易，但是您也可以添加源方法的名称并保留灵活性。(如果您不同意，请发表评论，我将提供代码)。

相关讨论