有沒有辦法讓類用sphinx繼承他們超類的文檔？

Question

假設我有一類

和子類

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

是有可能從A.myfunction與獅身人面像繼承B.myfunction的API文檔？ B.myfunction的文檔應該是「A」。以及。

Answer 1

在python中，您可以通過在創建對象的文檔後指定其「文檔字符串」__doc__來設置對象的文檔。最簡單的方法是使用一個裝飾器來複制父類的文檔字符串。你甚至可以爲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)。這很容易，但是你可能還需要添加源代碼方法的名稱並保留其靈活性。 （如果您不同意，評論和我會提供代碼）。