È possibile nascondere gli argomenti della funzione Python in Sphinx?

Question

Supponiamo che io ho la seguente funzione che viene documentata nel Numpydoc style, e la documentazione è generata automaticamente con il 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 

Non voglio pubblicizzare l'argomento nascosto come parte del mio pubblico API , ma si presenta nella mia documentazione generata automaticamente. C'è un modo per dire a Sphinx di ignorare un argomento specifico per una funzione, o (ancora meglio) renderlo auto-ignorare gli argomenti con un trattino basso principale?

Answer 1

Non credo ci sia un'opzione per questo in Sfinge. Un modo possibile per ottenere questo risultato senza dover incidere il codice, è usare la firma personalizzata.

In questo caso, è necessario qualcosa di simile:

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

Questo sostituirà l'elenco dei parametri della funzione e nascondere l'argomento indesiderato nel doc.

Answer 2

È possibile modificare la firma della funzione in un gestore per l'evento autodoc-process-signature.

Il parametro signature del gestore eventi mantiene la firma; una stringa del modulo (parameter_1, parameter_2). Nel frammento di seguito, split() viene utilizzato per rimuovere l'ultimo parametro di una funzione:

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) 

Il risultato è che la documentazione mostrerà la firma della funzione in questione come foo(x, y) invece di foo(x, y, _hidden_argument=None).