Czy można ukryć argumenty funkcji Pythona w Sphinx?

Question

Załóżmy, że mam następującą funkcję, która jest udokumentowana w Numpydoc style, a dokumentacja jest automatycznie generowane z Sphinxautofunction directive:

def foo(x, y, _hidden_argument=None): 
    """ 
    Foo a bar. 

    Parameters 
    ---------- 
    x: str 
     The first argument to foo. 
    y: str 
     The second argument to foo. 

    Returns 
    ------- 
    The barred foo. 

    """ 
    if _hidden_argument: 
     _end_users_shouldnt_call_this_function(x, y) 
    return x + y 

Nie chcę reklamować ukryty argument jako część mojego publicznych API , ale pojawia się w mojej generowanej automatycznie dokumentacji. Czy jest jakiś sposób, aby powiedzieć Sphinxowi, aby zignorował konkretny argument funkcji lub (nawet lepiej) sprawił, że automatycznie ignoruje argumenty z wiodącym podkreśleniem?

Answer 1

Nie sądzę, że istnieje taka opcja w przypadku Sfinksa. Jednym z możliwych sposobów osiągnięcia tego bez konieczności włamywania się do kodu jest użycie niestandardowego podpisu.

W tym przypadku trzeba coś takiego:

.. autofunction:: some_module.foo(x, y) 

to będzie zastąpić listę parametrów funkcji i ukryć niechciane argument w dok.

Answer 2

Możliwe jest edytowanie sygnatury funkcji w module obsługi dla zdarzenia autodoc-process-signature.

Parametr signature parametru obsługi zdarzenia zawiera podpis; ciąg w postaci (parameter_1, parameter_2). W poniższym fragmencie, split() służy do usuwania ostatniego parametru funkcji:

hidden = "_hidden_argument" 

def process_sig(app, what, name, obj, options, signature, return_annotation): 
    if signature and hidden in signature: 
     signature = signature.split(hidden)[0] + ")" 
    return (signature, return_annotation) 

def setup(app): 
    app.connect("autodoc-process-signature", process_sig) 

Powoduje to, że dokumentacja pokaże podpisu funkcji w pytaniu jak foo(x, y) zamiast foo(x, y, _hidden_argument=None).