14
Sto cercando di pulire la mia documentazione del codice Python e ho deciso di usare sphinx-doc perché sembra buono. Mi piace come posso fare riferimento altre classi e metodi con tag come:Come documentare i parametri della funzione Python con sphinx-apidoc
:class:`mymodule.MyClass` About my class.
:meth:`mymodule.MyClass.myfunction` And my cool function
Sto cercando di capire se come documentare i nomi dei parametri in una funzione, in modo che se ho una funzione come:
def do_this(parameter1, parameter2):
"""
I can describe do_this.
:something?:`parameter1` And then describe the parameter.
"""
Qual è la migliore pratica per questo?
Aggiornamento:
La sintassi corretta è:
def do_this(parameter1, parameter2):
"""
I can describe do_this.
:something parameter1: And then describe the variable
"""
Questi sono chiamati "elenchi di campi di informazioni". Vedi anche http://stackoverflow.com/questions/4547849/good-examples-of-python-docstrings-for-sphinx – gotgenes
Controlla il [Napolean] (http://www.sphinx-doc.org/en/stable /ext/napoleon.html) estensione per Sphinx, che consente le stringhe doc in [stile Google o Numpy] (http://www.sphinx-doc.org/en/stable/ext/napoleon.html#google-vs- numpy), entrambi sembrano più belli di quella semplice Sfinge. – cbare
Anche di interesse: http://www.pydev.org/manual_adv_type_hints.html –