Saltare i suggerimenti sul tipo nella documentazione

Aug 21 2020

Consideriamo la seguente funzione:

def f(x: int, y: int) -> int:
    """Get sum of two integers.

    Parameters
    ----------
    x : int
        first integer
    y : int
        second integer

    Returns
    -------
    int
        sum of the provided integers
    """
    return x + y

Durante la documentazione con Sphinx (v3.2.1), la documentazione viene generata nel seguente formato:

Tuttavia, non vedo un punto per mostrare i suggerimenti sul tipo come nell'intestazione f(x: int, y:int) -> intdella documentazione della funzione e anche nella Parameterssezione. In questo caso, non ha molta importanza, ma lo rende molto illeggibile con funzioni con 4-5 argomenti. C'è un modo per saltare il suggerimento sul tipo? Ad esempio, preferirò se l'intestazione è solo fo f(x, y).

Mi aspettavo che questo avesse qualcosa a che fare con add_function_parentheses, ma impostarlo come Falsein conf.pynon ha avuto alcun effetto che ho notato.

Un problema correlato è che se il suggerimento di tipo è lungo, potrebbe essere come typing.Unioncon più descrizioni lunghe, dove non voglio usare typing.Any, spesso scrivo quelli nella docstring su più righe, rispettando il limite massimo di righe. In questi casi, la Parameterssezione mostra che il tipo è ciò che è nella prima riga e le righe successive sono solo descrizioni. Non sto allegando un esempio di questo problema, poiché non sono sicuro che siano uguali o meno. Se lo sono, per favore fatemelo sapere e aggiornerò con un esempio.

Risposte

2 yarnabrina Aug 24 2020 at 19:07

C'è un'opzione autodoc_typehintsper sphinx.ext.autodoc. Questo ha 3 opzioni: nonee description( signaturepredefinito). L'utilizzo di noneo descriptionnasconderà i suggerimenti di tipo nella riga dell'intestazione. L'unica differenza che posso trovare tra questi due è che se le docstring non contengono suggerimenti di tipo, descriptionli mostreranno comunque nella documentazione che raccoglie dai suggerimenti di tipo.

Per utilizzare questo, sono necessarie le seguenti modifiche in conf.py:

  1. aggiungi sphinx.ext.autodoc( extensionsse non l'hai già fatto)
  2. impostareautodoc_typehints = "none"
1 mzjn Aug 23 2020 at 00:16

Un gestore per l' autodoc-process-signatureevento può modificare le firme e restituire annotazioni di funzioni e metodi.

Di seguito è riportato un semplice esempio. Se aggiungi questo codice a conf.py, tutte le firme e le annotazioni restituite vengono rimosse dall'output.

def fix_sig(app, what, name, obj, options, signature, return_annotation):
    return ("", "")
 
def setup(app):
    app.connect("autodoc-process-signature", fix_sig)