• 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
  • Herramientas
    • Método D’Hondt – Atribución de escaños
  • 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
  • Excel
  • IA Generativa

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

Tabla de contenidos

  • 1 Cadenas de documentación (“Docstring”)
  • 2 Tipos de documentación
    • 2.1 Documentación de clases
    • 2.2 Documentación de funciones
    • 2.3 Documentación de módulos o submódulos
  • 3 Formato de la documentación
  • 4 El archivo README.rst
  • 5 Inclusión de badges al documentar paquetes de Python
  • 6 Conclusiones

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.

Correlación y causalidad: no es lo mismo
En Analytics Lane
Correlación y causalidad: no es lo mismo

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.

Publicidad


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

Publicidad


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.

Publicidad


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.

Publicidad


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.

![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?

Publicidad


Publicaciones relacionadas

  • Correlación y causalidad: no es lo mismo
  • Cómo exportar un DataFrame de Pandas a Markdown en Python
  • Consistencia en nombres y orden en TypeScript: la base de un código mantenible aplicado a tslane
  • Análisis de Redes con Python
  • Nuevo calendario de publicaciones: más calidad, mejor ritmo
  • Probabilidad básica: cómo entender el azar en nuestra vida diaria
  • Cómo eliminar las noticias en Windows 11 y recuperar tu concentración
  • Publicaciones de verano 2025: los trucos más populares, ahora en vídeo
  • Cómo enviar correos desde PowerShell utilizando Brevo: Guía paso a paso para automatizar tus notificaciones

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.

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
  • Bluesky
  • Facebook
  • GitHub
  • Instagram
  • Mastodon
  • Pinterest
  • RSS
  • Telegram
  • Tumblr
  • Twitter
  • YouTube

Publicidad

Entradas recientes

¡Nuevo video! Encuentra la posición en listas como un PRO

julio 10, 2025 Por Daniel Rodríguez

Analytics Lane

1100 publicaciones en Analytics Lane

julio 9, 2025 Por Daniel Rodríguez

¡Nuevo video! 5 formas prácticas de obtener valores únicos en Pandas

julio 8, 2025 Por Daniel Rodríguez

Publicidad

Es tendencia

  • Copiar y pegar Activar copiar y pegar en VirtualBox publicado el mayo 1, 2019 | en Herramientas
  • Gráfico de densidad con relleno y escala de colores para el conjunto de 500 datos Gráficos de densidad: alternativa a los gráficos de dispersión en Python publicado el marzo 27, 2023 | en Python
  • Truco: reemplazar los valores NaN en los DataFrame Pandas publicado el mayo 30, 2022 | en Python
  • pandas Pandas: Contar los valores nulos en DataFrame publicado el agosto 12, 2021 | en Python
  • El índice de Davies-Bouldinen para estimar los clústeres en k-means e implementación en Python publicado el junio 30, 2023 | en Ciencia de datos

Publicidad

Lo mejor valorado

4.9 (24)

Seleccionar filas y columnas en Pandas con iloc y loc

4.6 (16)

Archivos JSON con Python: lectura y escritura

4.4 (14)

Ordenación de diccionarios en Python mediante clave o valor

4.7 (13)

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

4.5 (10)

Diferencias entre var y let en JavaScript

Publicidad

Comentarios recientes

  • Piera en Ecuaciones multilínea en Markdown
  • Daniel Rodríguez en Tutorial de Mypy para Principiantes
  • Javier en Tutorial de Mypy para Principiantes
  • javier en Problemas con listas mutables en Python: Cómo evitar efectos inesperados
  • soldado en Numpy básico: encontrar la posición de un elemento en un Array de Numpy

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-2025 Analytics Lane ·Términos y condiciones ·Política de Cookies ·Política de Privacidad ·Herramientas de privacidad ·Contacto