imprimir - print en python 3
¿Cuál es el formato estándar de documentación en Python? (8)
Los formatos
Las cadenas de documentación de Python se pueden escribir siguiendo varios formatos, como se muestra en las otras publicaciones. Sin embargo, el formato predeterminado de la cadena de documentación de Sphinx no se mencionó y se basa en reStructuredText (reST) . Puede obtener información sobre los formatos principales en ese tuto .
Tenga en cuenta que el PEP 287 recomienda el reST
A continuación se muestran los principales formatos utilizados para las cadenas de documentación.
- epytext
Históricamente, un estilo de estilo javadoc prevalecía, por lo que se tomó como base para Epydoc (con el formato llamado Epytext ) para generar documentación.
Ejemplo:
"""
This is a javadoc style.
@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""
- descanso
Hoy en día, el formato que probablemente prevalece es el formato reStructuredText (reST) que utiliza Sphinx para generar documentación. Nota: se utiliza de forma predeterminada en JetBrains PyCharm (escriba comillas triples después de definir un método y presione Intro). También se usa por defecto como formato de salida en Pyment.
Ejemplo:
"""
This is a reST style.
:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""
Google tiene su propio format que se utiliza a menudo. También puede ser interpretado por Sphinx (es decir, utilizando el complemento de Napoleón ).
Ejemplo:
"""
This is an example of Google style.
Args:
param1: This is the first param.
param2: This is a second param.
Returns:
This is a description of what is returned.
Raises:
KeyError: Raises an exception.
"""
Incluso mas ejemplos
- Numpydoc
Tenga en cuenta que Numpy recomienda seguir su propio numpydoc basado en el formato de Google y que Sphinx pueda utilizar.
"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.
Parameters
----------
first : array_like
the 1st param name `first`
second :
the 2nd param
third : {''value'', ''other''}, optional
the 3rd param, by default ''value''
Returns
-------
string
a value in a string
Raises
------
KeyError
when a key error
OtherError
when an other error
"""
Convertir / Generar
Es posible usar una herramienta como Pyment para generar automáticamente cadenas de documentos para un proyecto de Python que aún no se ha documentado, o para convertir cadenas de documentos existentes (pueden estar mezclando varios formatos) de un formato a otro.
Nota: Los ejemplos están tomados de la documentación de Pyment.
He visto algunos estilos diferentes de escritura de cadenas de documentación en Python, ¿hay un estilo oficial o "acordado"?
Como aparentemente nadie lo mencionó: también puede usar el Estándar de Numpy Docstring . Es ampliamente utilizado en la comunidad científica.
- La especificación del formato desde numpy junto con un example
- Tienes una extensión de esfinge para renderizarla: numpydoc
- Y un ejemplo de lo hermosa que puede ser una cadena de documentos renderizada: http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html
La extensión de esfinge de Napoleón para analizar las cadenas de documentación de estilo Google (recomendada en la respuesta de @Nathan) también es compatible con la cadena de documentación de estilo Numpy, y hace una breve comparison de ambas.
Y por último, un ejemplo básico para dar una idea de cómo se ve:
def func(arg1, arg2):
"""Summary line.
Extended description of function.
Parameters
----------
arg1 : int
Description of arg1
arg2 : str
Description of arg2
Returns
-------
bool
Description of return value
See Also
--------
otherfunc : some related other function
Examples
--------
These are written in doctest format, and should illustrate how to
use the function.
>>> a=[1,2,3]
>>> print [x + 3 for x in a]
[4, 5, 6]
"""
return True
Es Python; todo vale Considere cómo publicar su documentación . Las cadenas de documentos son invisibles excepto para los lectores de su código fuente.
A la gente realmente le gusta navegar y buscar documentación en la web. Para lograrlo, utiliza la herramienta de documentación Sphinx . Es el estándar de facto para documentar proyectos de Python. El producto es hermoso: eche un vistazo a https://python-guide.readthedocs.org/en/latest/ . El sitio web Leer los documentos alojará sus documentos de forma gratuita.
La guía de estilo de Google contiene una excelente guía de estilo de Python. Incluye convenciones para la sintaxis de la cadena de documentos legibles que ofrece una mejor orientación que PEP-257. Por ejemplo:
def square_root(n):
"""Calculate the square root of a number.
Args:
n: the number to get the square root of.
Returns:
the square root of n.
Raises:
TypeError: if n is not a number.
ValueError: if n is negative.
"""
pass
Me gusta extender esto para incluir también información de tipo en los argumentos, como se describe en este tutorial de documentación de Sphinx . Por ejemplo:
def add_value(self, value):
"""Add a new value.
Args:
value (str): the value to add.
"""
pass
Las convenciones de Docstring están en PEP-257 con mucho más detalle que PEP-8.
Sin embargo, las cadenas de documentación parecen ser mucho más personales que otras áreas de código. Los diferentes proyectos tendrán su propio estándar.
Tiendo a incluir siempre docstrings, porque tienden a demostrar cómo usar la función y lo que hace muy rápidamente.
Prefiero mantener las cosas coherentes, independientemente de la longitud de la cadena. Me gusta cómo codificar las apariencias cuando la sangría y el espaciado son consistentes. Eso significa, yo uso:
def sq(n):
"""
Return the square of n.
"""
return n * n
Terminado:
def sq(n):
"""Returns the square of n."""
return n * n
Y tienden a dejar de comentar en la primera línea en cadenas de documentación más largas:
def sq(n):
"""
Return the square of n, accepting all numeric types:
>>> sq(10)
100
>>> sq(10.434)
108.86835599999999
Raises a TypeError when input is invalid:
>>> sq(4*''435'')
Traceback (most recent call last):
...
TypeError: can''t multiply sequence by non-int of type ''str''
"""
return n*n
Lo que significa que me parece que las cadenas de documentación que comienzan así son desordenadas.
def sq(n):
"""Return the squared result.
...
Los estilos oficiales de Python están listados en python.org/dev/peps/pep-0008 .
Sugiero usar el programa pep257 Python de Vladimir Keleshev para verificar sus cadenas de documentación contra PEP-257 y el Estándar de Numpy Docstring para describir parámetros, devoluciones, etc.
pep257 informará de la divergencia que haga del estándar y se llamará como pylint y pep8.