about 4 years ago

今天遇到了 Sphinx 讀取有 decorator 的函數時,抓不到 docstring 的問題。原因出在寫 decorator 時沒有把函數特徵保留給要回傳的的函數。

因為 decorator 的原理是 my_function = my_decorator(my_function)。因此得到的函數特徵是 my_decorator 這個函數的,而不是原先 my_function 的。解決方式是利用 functools 裡面的 wraps 函數將特徵轉移給新的回傳函數。

範例:

from functools import wraps

def my_decorator(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

如果改完之後,docstring 還是沒有出現,有可能是你改的地方是 decorator 本身,Sphinx 誤以為現有函數並沒有修改,而沒有重新讀取,這時只要將 _build 砍掉重編就會出現了。

參考資料

  1. Python Sphinx autodoc and decorated members
← Sphinx Documentation 初體驗 Git Subtree 試用 →
 
comments powered by Disqus