Formatos
Las cadenas de documentos de Python se pueden escribir siguiendo varios formatos como mostraron las otras publicaciones. Sin embargo, el formato de cadena de documentación predeterminado de Sphinx no se mencionó y se basa en reStructuredText (reST) . Puede obtener información sobre los formatos principales en esta publicación de blog .
Tenga en cuenta que la PEP 287 recomienda la reST
A continuación se muestran los principales formatos utilizados para las cadenas de documentos.
- Epytext
Históricamente , prevalecía un estilo similar al javadoc , por lo que se tomó como base para Epydoc (con el Epytext
formato llamado ) 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 probablemente más frecuente es el formato reStructuredText (reST) que Sphinx utiliza para generar documentación. Nota: se usa por defecto en JetBrains PyCharm (escriba comillas triples después de definir un método y presione enter). También se usa de forma predeterminada 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
Google tiene su propio formato que a menudo se usa. 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.
"""
Aún más ejemplos
- Numpydoc
Tenga en cuenta que Numpy recomienda seguir su propio numpydoc basado en el formato de Google y que Sphinx pueda usar.
"""
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 utilizar una herramienta como Pyment para generar automáticamente docstrings a un proyecto de Python aún no documentado, o para convertir docstrings existentes (puede estar mezclando varios formatos) de un formato a otro.
Nota: Los ejemplos se toman de la documentación de pago