Una vez creadas las funciones y las clases de nuestro paquete es necesario escribir la documentación para que otros usuarios puedan saber cómo usarlas. Documentación que debe ofrecer información concisa sobre el funcionamiento de los componentes. En esta sexta entrada de la serie “Creación de un paquete de Python” vamos a ver cómo documentar paquetes de Python, escribiendo la documentación tanto del paquete como de las funciones y clases.
Esta entrada forma parte de la colección “Creación de paquetes de Python” que consta de las siguientes siete entradas:
- Creación de paquetes de Python
- Pruebas unitarias en Python
- Probar en múltiples versiones de Python
- Cobertura de las pruebas unitarias en Python
- Gestionar las dependencias de paquetes Python
- Documentar paquetes de Python
- Distribuir paquetes de Python
Cadenas de documentación (“Docstring”)
La documentación de las funciones de Python se realiza mediante cadenas de documentación (“Docstring”). Una cadenas que se incluyen dentro de código para que los usuarios puedan consultarlas mediante la función nativa de Python help(). La cual imprimirá la cadena de documentación del objeto solictado.
Las cadenas de documentación se tienen que incluir inmediatamente después de la línea en la que define el objeto. Para lo que se debe utilizar siempre cadenas de texto con comillas dobles triple, incluso cuando la documentación solamente conste de una línea. Es importante que ninguna de las líneas de la documentación supere los 72 caracteres para que se pueda consultar en terminales.
Generalmente las cadenas de documentación contarán tendrán más de una línea para explicar el funcionamiento de elemento. En estos casos la estructura básica de la documentación es:
- Una primera línea de resumen
- Una línea en blanco
- Varias líneas donde se ofrece más detalles
- Una línea en blanco.
Tipos de documentación
La documentación de los paquetes de Python se puede dividir en tres clases principales: clases, funciones y módulos o submódulos.
Documentación de clases
Las cadenas de documentación de las clases se tienen que escribir tanto para la clase en sí, como para los diferentes métodos de la clase. En ambos casos se tiene que situar inmediatamente después de la clase o el método con un sangrado. Por ejemplo tal como se muestra en el siguiente ejemplo.
class ClaseEjemplo:
"""Documentación de la clase"""
def metodo(self):
"""Documentación del método"""
passDocumentación de funciones
La documentación de las funciones se incluye inmediatamente después de la definición de estas con un sagrado. Exactamente igual que en el caso de los métodos de las clases. Por ejemplo, como se muestra a continuación:
def funcion(self):
"""Documentación de la función."""Documentación de módulos o submódulos
Finalmente, la documentación de los módulos o submódulos se sitúa al comienzo de los archivos __init__.py que se deben situar en la carpeta del proyecto y todas las subcarpetas. Esta documentación debe incluir una descripción del módulo y una lista de las clases, funciones y módulos que exporta.
Formato de la documentación
Existen diferentes estándares para escribir las cadenas de documentación. Entre los más populares se puede encontrar Google docstrings, reStructure y NumPy/SciPy docstrings. Siendo este último el que elegiremos para nuestro proyecto.
La documentación tipo NumPy/SciPy comienza con una descripción de lo que se está documentando. Posteriormente se indica cuales son los parámetros, para lo que se inicia una sección llamada Parameters. En esta sección se indica el nombre del parámetro, seguido de dos puntos y el tipo. En la siguiente línea con sangrado se describe el qué se espera. Al final se el tipo de dato que se devuelve, si el método o la función devuelve uno, y una descripción de este.
"""Descripción de la función
Parameters
----------
parametro_1 : tipo
Descripción del parametro
parametro_2 : tipo
Descripción del parametro
Returns
-------
tipo
Descripción de los valores que devuelve
"""El archivo README.rst
Si no hemos fijado en nuestro paquete podemos observar que en la raíz de este se incluye un archivo llamado README.rst. Este archivo Incluye documentación del paquete en reStructure y es necesario para publicar el paquete en PyPi.
En el caso de que no deseemos aprender este formato y estemos acostumbrados a documentar nuestro paquete con un documento markdown, como suele ser habitual en GitHub, podemos convertir uno en otro con pandoc. Para ellos solamente es necesario instalar la herramienta en nuestro sistema y ejecutar la siguiente línea en la terminal.
pandoc --from=markdown --to=rst --output=README.rst README.md
Con lo que crearemos una copia del README.md en formato reStructure.
Inclusión de badges al documentar paquetes de Python
Tanto el archivo README.rst como README.md pueden contener “badges”. Unas insignias mediante las que indicar la ultima versión publicada en PyPi, el grado de cobertura de las pruebas, la “calidad” del código, etc. Estas no son más que enlaces a los servicios que ofrecen estos resultados y se para cada uno de ellos se puede consultar cómo conseguir la insignia en Shields.io.
Así podemos mostrar por ejemplo la licencia de y el tamaño del repositorio con las siguientes líneas de Markdown.
 
Lo que produce el siguiente ejemplo.
Conclusiones
En esta entrada hemos visto cómo documentar paquetes en Python, algo que es importante tanto para nuestros usuarios como nosotros mismos. La próxima semana se explicará los métodos disponibles para distribuir los paquetes, viendo las opciones más habituales como puede ser GitHub, archivos o PyPi.
Deja una respuesta