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

restructuredtext documentation

Question

Estoy tratando de limpiar la documentación de mi código python, y decidí usar sphinx-doc porque se ve bien. Me gusta cómo puedo hacer referencia a otras clases y métodos con etiquetas como:

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

Estoy tratando de averiguar cómo documentar los nombres de los parámetros en una función, de modo 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?

Actualizar:

La sintaxis correcta es:

def do_this(parameter1, parameter2):
"""
I can describe do_this.
:something parameter1: And then describe the variable
"""

Answer 1

Añadiendo esta respuesta para consolidar las opciones:

pydoc es básico sin formato especial.

epydoc utiliza el formato ''@param var:''

Doxygen está orientado a una mayor variedad de idiomas.

Sphinx usa el formato '': param type var:''. También vea más ejemplos . Esto se utilizó para crear la documentación de Python 3.5 .

Answer 2

Normalmente, las "variables de función" se denominan parámetros;).

Se documenta aquí: http://sphinx.pocoo.org/domains.html#signatures

Y la respuesta es :param ________

EDITAR Descargo de responsabilidad: nunca he usado ni oído hablar de la esfinge ... Esta publicación es principalmente un "qué palabras buscar". Espero que haya ayudado.