Cómo documentar los parámetros de la función Python con sphinx-apidoc

Estoy tratando de limpiar mi documentación de código python, y decidí usar sphinx-doc porque se ve bien. Me gusta la forma en que puedo hacer referencia a otras clases y métodos con etiquetas como:Cómo documentar los parámetros de la función Python con sphinx-apidoc

:class:`mymodule.MyClass` About my class. 
:meth:`mymodule.MyClass.myfunction` And my cool function

que estoy tratando de averiguar cómo documentar aunque los nombres de parámetros en una función, por lo que si tengo una función como:

def do_this(parameter1, parameter2): 
    """ 
    I can describe do_this. 

    :something?:`parameter1` And then describe the parameter. 

    """

¿Cuál es la mejor práctica para esto?

Actualización:

La sintaxis correcta es:

def do_this(parameter1, parameter2): 
    """ 
    I can describe do_this. 

    :something parameter1: And then describe the variable 
    """

Fuente

2012-03-02 Adam Morris

Esas llamadas "listas de campos de información". Ver también http://stackoverflow.com/questions/4547849/good-examples-of-python-docstrings-for-sphinx – gotgenes

Echa un vistazo a [Napolean] (http://www.sphinx-doc.org/en/stable /ext/napoleon.html) extensión para Sphinx, que permite cadenas de documentos en [estilo Google o Numpy] (http://www.sphinx-doc.org/en/stable/ext/napoleon.html#google-vs- numpy), los cuales se ven más bonitos que la simple Sphinx. – cbare

También de interés: http://www.pydev.org/manual_adv_type_hints.html –

Típicamente "variables de la función" se denominan parámetros;).

Está documentado aquí: http://sphinx.pocoo.org/domains.html#signatures

Y la respuesta es :param ________

EDITAR responsabilidad: nunca he utilizado o escuchado de esfinge ... Este post es sobre todo un "qué palabras a buscar " Espero que haya ayudado.

Fuente

2012-03-02 14:02:51 Crisfole

Gracias ... Estaba buscando algo equivocado. Había intentado param en algún momento, pero seguí recibiendo errores, y no me di cuenta de que la sintaxis no era: param: 'variable1', pero: param variable1: –

http://sphinx-doc.org/domains.html#id1 y https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions – ddotsenko

Convenios para documentar parámetros complejos (listas, dicts, etc.) - https://www.jetbrains.com/pycharm/webhelp/type-hinting-in -pycharm.html – ddotsenko

La adición de esta respuesta para consolidar opciones:

pydoc es básico sin formato especial

epydoc utiliza el formato '@param var:'

Doxygen está orientado para una gama más amplia de idiomas

Sphinx usa el formato ': param type var:'. También vea more examples. Esto se utilizó para crear el Python 3.5 documentation.

Fuente

2015-09-21 16:37:29

Cómo documentar los parámetros de la función Python con sphinx-apidoc

Respuesta

Cuestiones relacionadas