我可以在Sphinx文檔中抑制變量擴展嗎？

Question

在我的代碼有

X_DEFAULT = ['a', 'long', 'list', 'of', 'values', 'that', 'is', 'really', 'ugly', 'to', 'see', 'over', 'and', 'over', 'again', 'every', 'time', 'it', 'is', 'referred', 'to', 'in', 'the', 'documentation'] 

後來

def some_function(..., x=X_DEFAULT, ...): 

讓我的獅身人面像文檔中，使用（例如，使用.. autofunction::等），我得到的X_DEFAULT整個長而笨重值在簽名擴大了some_function：

some_function（...，X = [ '一'， '長'， '名單'， '中'， '值'， '那個'， '是'， '真'， '醜'， '對'，'見「‘過’，‘和’，‘過’，‘又’， ‘每一個’，‘時間’，‘它’，‘是’，‘所指’，‘到’，‘’，」的」， '文件']，...）

有沒有辦法抑制這種替代所產生的文檔中，最好有一個鏈接回X_DEFAULT定義：

some_function（ ...，x = X_DEFAULT ...）

---

我知道，我可以手動覆蓋每個函數和方法，我明確列出作爲參數傳遞給獅身人面像文檔指令簽名，但在這裏，這不是我的目標。我也知道，我可以用autodoc_docstring_signature和文檔字符串的第一行，但這樣會產生不好的文檔字符串，真正用於何處反省失敗（如C）的情況。我懷疑我可以在autodoc-process-signature中做些什麼，但這可能是足夠的（但並不完美），儘管我不確定如何繼續。

Answer 1

的一種方法，這種意願，例如，「還原」已在模塊級別被定義爲「公共常量」爲其中一個唯一的名稱（由全大寫的無前導下劃線名識別）的所有值的置換可以在其被限定的模塊中找到：

def pretty_signature(app, what, name, obj, options, signature, return_annotation): 
    if what not in ('function', 'method', 'class'): 
     return 

    if signature is None: 
     return 

    import inspect 
    mod = inspect.getmodule(obj) 

    new_sig = signature 
    # Get all-caps names with no leading underscore 
    global_names = [name for name in dir(mod) if name.isupper() if name[0] != '_'] 
    # Get only names of variables with distinct values 
    names_to_replace = [name for name in global_names 
         if [mod.__dict__[n] for n in global_names].count(mod.__dict__[name]) == 1] 
    # Substitute name for value in signature, including quotes in a string value 
    for var_name in names_to_replace: 
     var_value = mod.__dict__[var_name] 
     value_string = str(var_value) if type(var_value) is not str else "'{0}'".format(var_value) 
     new_sig = new_sig.replace(value_string, var_name) 

    return new_sig, return_annotation 

def setup(app): 
    app.connect('autodoc-process-signature', pretty_signature) 

---

另一種方法是簡單地直接從源取的文檔字符串：

import inspect 
import re 

def pretty_signature(app, what, name, obj, options, signature, return_annotation): 
    """Prevent substitution of values for names in signatures by preserving source text.""" 
    if what not in ('function', 'method', 'class') or signature is None: 
     return 

    new_sig = signature 
    if inspect.isfunction(obj) or inspect.isclass(obj) or inspect.ismethod(obj): 
     sig_obj = obj if not inspect.isclass(obj) else obj.__init__ 
     sig_re = '\((self|cls)?,?\s*(.*?)\)\:' 
     new_sig = ' '.join(re.search(sig_re, inspect.getsource(sig_obj), re.S).group(2).replace('\n', '').split()) 
     new_sig = '(' + new_sig + ')' 

    return new_sig, return_annotation