Saltare i suggerimenti sul tipo nella documentazione
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) -> int
della documentazione della funzione e anche nella Parameters
sezione. 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 f
o f(x, y)
.
Mi aspettavo che questo avesse qualcosa a che fare con add_function_parentheses
, ma impostarlo come False
in conf.py
non ha avuto alcun effetto che ho notato.
Un problema correlato è che se il suggerimento di tipo è lungo, potrebbe essere come typing.Union
con 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 Parameters
sezione 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
C'è un'opzione autodoc_typehintsper sphinx.ext.autodoc
. Questo ha 3 opzioni: none
e description
( signature
predefinito). L'utilizzo di none
o description
nasconderà 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, description
li mostreranno comunque nella documentazione che raccoglie dai suggerimenti di tipo.
Per utilizzare questo, sono necessarie le seguenti modifiche in conf.py
:
- aggiungi
sphinx.ext.autodoc
(extensions
se non l'hai già fatto) - impostare
autodoc_typehints = "none"
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)