• Saltar al contenido principal
  • Skip to secondary menu
  • Saltar a la barra lateral principal
  • Saltar al pie de página
  • Inicio
  • Secciones
    • Ciencia de datos
    • Criptografía
    • Herramientas
    • Machine Learning
    • Noticias
    • Opinión
    • Productividad
    • Programación
      • JavaScript
      • Julia
      • Matlab
      • Python
      • R
  • Programación
    • JavaScript
    • Julia
    • Matlab
    • Python
    • R
  • Noticias
  • Boletín
  • Contacto
  • Tienda
    • Libros
    • Equipamiento de oficina
    • Equipamiento en movilidad
    • Tiendas afiliadas
      • AliExpress
      • Amazon
      • Banggood
      • GeekBuying
      • Lenovo

Analytics Lane

Ciencia e ingeniería de datos aplicada

  • Ciencia de datos
  • Machine Learning
  • Python
  • Pandas
  • NumPy
  • Matlab
  • Julia
  • JavaScript
  • Excel

Documentar paquetes de Python (Creación de paquetes de Python 6ª parte)

marzo 27, 2020 Por Daniel Rodríguez Deja un comentario
Tiempo de lectura: 5 minutos

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:

  1. Creación de paquetes de Python
  2. Pruebas unitarias en Python
  3. Probar en múltiples versiones de Python
  4. Cobertura de las pruebas unitarias en Python
  5. Gestionar las dependencias de paquetes Python
  6. Documentar paquetes de Python
  7. 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:

Publicidad


  • 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"""

        pass

Documentació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.

Publicidad


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.

Publicidad


Así podemos mostrar por ejemplo la licencia de y el tamaño del repositorio con las siguientes líneas de Markdown.

![GitHub repo size](https://img.shields.io/github/repo-size/analyticslane/pylane)
![GitHub](https://img.shields.io/github/license/analyticslane/pylane)

Lo que produce el siguiente ejemplo.

GitHub repo size GitHub

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.

Imagen de seth0s en Pixabay

¿Te ha parecido de utilidad el contenido?

¡Puntúalo entre una y cinco estrellas!

Puntuación promedio 0 / 5. Votos emitidos: 0

Ya que has encontrado útil este contenido...

¡Síguenos en redes sociales!

¡Siento que este contenido no te haya sido útil!

¡Déjame mejorar este contenido!

Dime, ¿cómo puedo mejorar este contenido?

Publicaciones relacionadas

  • Pruebas unitarias en Python (Creación de paquetes de Python 2ª parte)
    Pruebas unitarias en Python (Creación de paquetes de Python…
  • Clases abstractas en Python
    Clases abstractas en Python
  • Métodos mágicos de las clases Python
    Métodos mágicos de las clases Python
  • Realizar auditorías de código Python automáticamente
    Realizar auditorías de código Python automáticamente
  • Análisis de sentimientos con NLTK en Python
    Análisis de sentimientos con NLTK en Python
  • Cómo leer y escribir archivos en Python
    Cómo leer y escribir archivos en Python

Publicado en: Python

Interacciones con los lectores

Deja una respuesta Cancelar la respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

I accept the Terms and Conditions and the Privacy Policy

Este sitio usa Akismet para reducir el spam. Aprende cómo se procesan los datos de tus comentarios.

Publicidad




Barra lateral principal

Suscríbete a nuestro boletín

Suscríbete al boletín semanal para estar al día de todas las publicaciones.

Política de Privacidad

Analytics Lane en redes sociales

  • Amazon
  • Facebook
  • GitHub
  • Instagram
  • Pinterest
  • RSS
  • Twitter
  • Tumblr
  • YouTube

Publicidad

Entradas recientes

El método de Hare-Niemeyer y su implementación en Python

septiembre 29, 2023 Por Daniel Rodríguez

Redimensionar una partición de disco LVM con espacio no asignado en Linux

septiembre 27, 2023 Por Daniel Rodríguez

¿Cómo saber la versión de Pandas o cualquier otra librería en Python?

septiembre 25, 2023 Por Daniel Rodríguez

Publicidad

Es tendencia

  • Unir y combinar dataframes con pandas en Python publicado el septiembre 10, 2018 | en Python
  • ¿Cómo cambiar el nombre de las columnas en Pandas? publicado el mayo 6, 2019 | en Python
  • Enviar mensajes de WhatsApp con Python publicado el marzo 7, 2022 | en Python
  • Sistema de ecuaciones Sistemas de ecuaciones lineales con numpy publicado el octubre 29, 2018 | en Python
  • Ecuaciones multilínea en Markdown publicado el septiembre 14, 2022 | en Herramientas

Publicidad

Lo mejor valorado

4.9 (22)

Seleccionar filas y columnas en Pandas con iloc y loc

4.7 (12)

Operaciones de filtrado de DataFrame con Pandas en base a los valores de las columnas

4.6 (15)

Archivos JSON con Python: lectura y escritura

4.5 (10)

Diferencias entre var y let en JavaScript

4.3 (12)

Ordenación de diccionarios en Python mediante clave o valor

Publicidad

Comentarios recientes

  • Daniel Rodríguez en ¿Cómo eliminar columnas y filas en un dataframe pandas?
  • Miguel en ¿Cómo eliminar columnas y filas en un dataframe pandas?
  • alberto en Resolver problema de credenciales en Bitbucket
  • Pablo en Aplicar el método D’Hondt en Excel
  • Agapito en Creación de un EXE desde un archivo Python en Windows

Publicidad

Footer

Analytics Lane

  • Acerca de Analytics Lane
  • Boletín de noticias
  • Contacto
  • Libros
  • Lo más popular
  • Noticias
  • Tienda
  • Tiendas afiliadas

Secciones

  • Ciencia de datos
  • Criptografía
  • Herramientas
  • Machine Learning
  • Opinión
  • Productividad
  • Programación
  • Reseñas

Sobre de Analytics Lane

En Analytics Lane tratamos de explicar los principales conceptos de la ciencia e ingeniería de datos con un enfoque práctico. Los principales temas tratados son ciencia de datos, ingeniería de datos, inteligencia artificial, machine learning, deep learning y criptografía. Además, también se habla de los principales lenguajes de programación y herramientas utilizadas por los científicos e ingenieros de datos.

Copyright © 2018-2023 Analytics Lane ·Términos y condiciones ·Política de Cookies ·Política de Privacidad ·Herramientas de privacidad ·Contacto