Unificar docstrings de modules

[AlexS12]

Cada module (cada .py) que tenemos tiene un pequeño docstring al principio con una breve descripción. Spyder pone automáticamente el autor y la fecha. Deberíamos ponernos de acuerdo sobre qué incluir en cada uno y dejarlos todos con el mismo formato. Más que nada porque se usan para generar la documentación.

¿Propuestas? Podemos buscar lo que se incluye en los docstrings de otros paquetes y fijar en base a eso nuestro estilo.

Me encargo de cambiarlos una vez que lleguemos a un acuerdo.

[AlexS12]

Como preguntas:

• ¿Es necesario o útil poner la licencia en cada uno?
• ¿Conservamos los nombres de quien ha hecho cada module? En caso de que sí ¿qué pasa si alguien añade o cambia cosas?
• ¿Es útil o necesario que figure la fecha?
• ¿Es repetitivo poner en todos Equipo AeroPython?
• ¿Es útil o estándar listar las funciones que contienen?
  ...

Como decía, hace falta ver qué hace el resto del mundo y ver también qué es lo que como grupo nos interesa más.

[astrojuanlu]

En general yo propondría no incluir la información que ya esté en el control de versiones, concretamente los autores y la fecha, por redundante.

Se pueden poner unas líneas de este tipo:

https://github.com/jupyter/notebook/blob/4.1.0/notebook/notebookapp.py#L4-L5

# Copyright (c) AeroPython Development Team.
# Distributed under the terms of the MIT License.

[AlexS12]

¿Qué os parece lo siguiente?

 # -*- coding: utf-8 -*-
"""
Python Flight Mechanics Engine (PyFME).
Copyright (c) AeroPython Development Team. 
Distributed under the terms of the MIT License.

<Module name>
-------------
<Brief description ...>
< ... >

"""

He visto que en los __init__.py de NumPy se listan las funciones del paquete, por ejemplo:

"""
Core Linear Algebra Tools
=========================

=============== ==========================================================
Linear algebra basics
==========================================================================
norm            Vector or matrix norm
inv             Inverse of a square matrix
solve           Solve a linear system of equations
det             Determinant of a square matrix
slogdet         Logarithm of the determinant of a square matrix
lstsq           Solve linear least-squares problem
pinv            Pseudo-inverse (Moore-Penrose) calculated using a singular
                value decomposition
matrix_power    Integer power of a square matrix
matrix_rank     Calculate matrix rank using an SVD-based method
=============== ==========================================================

=============== ==========================================================
Eigenvalues and decompositions
==========================================================================
eig             Eigenvalues and vectors of a square matrix
...
=============== ==========================================================

=============== ==========================================================
Tensor operations
==========================================================================
tensorsolve     Solve a linear tensor equation
tensorinv       Calculate an inverse of a tensor
=============== ==========================================================

=============== ==========================================================
Exceptions
==========================================================================
LinAlgError     Indicates a failed linear algebra operation
=============== ==========================================================

"""

Aunque también incluyen un archivo info.py, que se importa desde el __init__.py : from .info import __doc__ y que tiene un docstring más bonito:

"""\
Core Linear Algebra Tools
-------------------------
Linear algebra basics:

- norm            Vector or matrix norm
- inv             Inverse of a square matrix
- solve           Solve a linear system of equations
- det             Determinant of a square matrix
- lstsq           Solve linear least-squares problem
- pinv            Pseudo-inverse (Moore-Penrose) calculated using a singular
                  value decomposition
- matrix_power    Integer power of a square matrix

Eigenvalues and decompositions:

- eig             Eigenvalues and vectors of a square matrix
- eigh            Eigenvalues and eigenvectors of a Hermitian matrix
- eigvals         Eigenvalues of a square matrix
- eigvalsh        Eigenvalues of a Hermitian matrix
- qr              QR decomposition of a matrix
- svd             Singular value decomposition of a matrix
- cholesky        Cholesky decomposition of a matrix

Tensor operations:

- tensorsolve     Solve a linear tensor equation
- tensorinv       Calculate an inverse of a tensor

Exceptions:

- LinAlgError     Indicates a failed linear algebra operation

"""

¿Cómo lo veis?

En cuanto lo aprobemos, esto va a la wiki y los vamos cambiando. 🚀

[astrojuanlu]

Listar todas las funciones me resultaría un poco redundante (el listado se
genera automáticamente en Sphinx de todas formas) pero la cabecera del
principio (con la atribución, el copyright y una descripción) me parece
correcta y necesaria 👍
On 29 Jan 2016 19:03, "Álex Sáez" notifications@github.com wrote:

¿Qué os parece lo siguiente?

-- coding: utf-8 --

"""
Python Flight Mechanics Engine (PyFME).
Copyright (c) AeroPython Development Team.
Distributed under the terms of the MIT License.

<Brief description ...>
< ... >

"""

He visto que en los init.py de NumPy se listan las funciones del
paquete, por ejemplo:

"""

Core Linear Algebra Tools

=============== ==========================================================

Linear algebra basics

norm Vector or matrix norm
inv Inverse of a square matrix
solve Solve a linear system of equations
det Determinant of a square matrix
slogdet Logarithm of the determinant of a square matrix
lstsq Solve linear least-squares problem
pinv Pseudo-inverse (Moore-Penrose) calculated using a singular
value decomposition
matrix_power Integer power of a square matrix
matrix_rank Calculate matrix rank using an SVD-based method
=============== ==========================================================

=============== ==========================================================

Eigenvalues and decompositions

eig Eigenvalues and vectors of a square matrix
...
=============== ==========================================================

=============== ==========================================================

Tensor operations

tensorsolve Solve a linear tensor equation
tensorinv Calculate an inverse of a tensor
=============== ==========================================================

=============== ==========================================================

Exceptions

LinAlgError Indicates a failed linear algebra operation
=============== ==========================================================

"""

Aunque también incluyen un archivo info.py, que se importa desde el
init.py : from .info import doc y que tiene un docstring más
bonito:

"""\

Core Linear Algebra Tools

Linear algebra basics:

• norm Vector or matrix norm
• inv Inverse of a square matrix
• solve Solve a linear system of equations
• det Determinant of a square matrix
• lstsq Solve linear least-squares problem
• pinv Pseudo-inverse (Moore-Penrose) calculated using a singular
  value decomposition
• matrix_power Integer power of a square matrix

Eigenvalues and decompositions:

• eig Eigenvalues and vectors of a square matrix
• eigh Eigenvalues and eigenvectors of a Hermitian matrix
• eigvals Eigenvalues of a square matrix
• eigvalsh Eigenvalues of a Hermitian matrix
• qr QR decomposition of a matrix
• svd Singular value decomposition of a matrix
• cholesky Cholesky decomposition of a matrix

Tensor operations:

• tensorsolve Solve a linear tensor equation
• tensorinv Calculate an inverse of a tensor

Exceptions:

• LinAlgError Indicates a failed linear algebra operation

"""

¿Cómo lo veis?

En cuanto lo aprobemos, esto va a la wiki y los vamos cambiando. [image:
🚀]

—
Reply to this email directly or view it on GitHub
#49 (comment).

[AlexS12]

Si no hay más que decir a lo anterior, vamos a establecer esta cabecera como cabecera oficial. Todos los pull request que se acepten a partir de ahora deben incorporarla. Los modules anteriores se irán cambiando en la medida de lo posible para que se genere una documentación homogénea.

 # -*- coding: utf-8 -*-
"""
Python Flight Mechanics Engine (PyFME).
Copyright (c) AeroPython Development Team. 
Distributed under the terms of the MIT License.

<Module name>
-------------
<Brief description ...>
< ... >

"""

Podéis cambiar el archivo template.py de vuestra carpeta de configuración de Spyder, si queréis, para que os aparezca automáticamente al crear un nuevo module.

@Juanlu001, ¿es necesario realemente el # -*- coding: utf-8 -*-? He visto que habías publicado algo al respecto el fin de semana en Twitter.

[astrojuanlu]

El # coding: utf-8 (así de esta forma también vale) es porque que el intérprete de Python Legacy (también conocido como Python 2) solía morir si no se ponía y había caracteres especiales en el archivo:

https://www.python.org/dev/peps/pep-0263/

Como si no me equivoco aún soportamos Python Legacy, no queda más remedio que dejarlo no nos vayamos a encontrar alguna sorpresa (por ejemplo, poner tildes en nuestros apellidos...)

[AlexS12]

Dejo escrito esto en la wiki con las pautas a seguir:
https://github.com/AeroPython/PyFME/wiki/Documentation-&-docstrings

[AlexS12]

Según lo comentado en la reunión 23/03/2016 se adopta el docstring de la wiki https://github.com/AeroPython/PyFME/wiki/Documentation-&-docstrings

Se irán modificando los modules antiguos sin prisa, pero se debe incorporar en los nuevos sin excepción.

Se queda el issue abierto, hasta que todo el paquete haya adoptado el formato.