He visto algunos estilos diferentes de escribir cadenas de documentos en Python, ¿hay un estilo oficial o "acordado"?

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 Epytextformato 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

La guía de estilo de Google contiene una excelente guía de estilo de Python. Incluye convenciones para una sintaxis de cadena de documentos legible 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 gustaría 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 documentos 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 cadenas de documentos, porque tienden a demostrar cómo usar la función y lo que hace muy rápidamente.

Prefiero mantener las cosas consistentes, independientemente de la longitud de la cadena. Me gusta cómo codificar las miradas cuando la sangría y el espaciado son consistentes. Eso significa que 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 documentos 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 encuentro que las cadenas de documentos que comienzan así son desordenadas.

def sq(n):
    """Return the squared result. 
    ...

Como aparentemente nadie lo mencionó: también puede usar el Estándar Numpy Docstring . Es ampliamente utilizado en la comunidad científica.

• La especificación del formato de numpy junto con un ejemplo
• Tiene una extensión de esfinge para representarla: numpydoc
• Y un ejemplo de lo hermosa que puede ser una cadena de documentación renderizada: http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

La extensión de la esfinge de Napolean para analizar las cadenas de documentos al estilo de Google (recomendada en la respuesta de @Nathan) también admite la cadena de documentos al estilo Numpy, y hace una breve comparación 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

PEP-8 es el estándar oficial de codificación de python. Contiene una sección sobre cadenas de documentos, que se refiere a PEP-257 , una especificación completa para cadenas de documentos.

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 lograr eso, use 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 Read the Docs alojará sus documentos de forma gratuita.

Sugiero usar el programa pep257 Python de Vladimir Keleshev para verificar sus cadenas de documentos con PEP-257 y el Estándar de Numpy Docstring para describir parámetros, devoluciones, etc.

pep257 informará la divergencia que realice del estándar y se llama pylint y pep8.