• 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
  • Laboratorio
    • Estadística
      • Calculadora del Tamaño Muestral en Encuestas
      • Calculadora de estadísticos descriptivos
      • Test de normalidad
      • Calculadora de contrastes de hipotesis
      • Calculadora de tamano del efecto
      • Simulador de Regresión Lineal con Ruido
      • Descenso de gradiente
      • Visualizador de PCA
      • Visualizador de Series Temporales
      • Simulador de Regresión Logística
      • Matriz de confusión e informe de clasificación
      • Visualizador de fronteras de decisión
      • Simulador de K-Means
      • Número Óptimo de Clusters
      • Simulador de DBSCAN
      • Detector de la Ley de Benford
      • Ajuste de Curvas
      • Calculadora de Matrices
    • Probabilidad
      • Calculadora de Probabilidad de Distribuciones
      • Problema del cumpleaños
      • Calculadora de Probabilidades de Lotería
      • Simulador del Problema de Monty Hall
      • La aguja de Buffon
      • Simulador de la Estrategia Martingala
      • Simulador de Cadenas de Markov
    • Finanzas
      • Calculadora de Préstamos e Hipotecas
      • Conversor TIN ↔ TAE
      • Calculadora DCA con ajuste por inflación
      • Comparador de tarifas de luz 2.0TD
      • Calculadora XIRR con Flujos Irregulares
      • Simulador FIRE (Financial Independence, Retire Early)
      • Frontera Eficiente
    • Negocios
      • CLV
      • Scoring
    • Herramientas
      • Formateador / Minificador de JSON
      • Conversor CSV ↔ JSON
      • Consultar CSV con SQL en el navegador
      • Extractor de tickets (OCR)
      • Comparador y Formateador de Texto y JSON
      • Formateador y Tester de Expresiones Regulares
      • Inspector de JWT
      • Generador y verificador de hashes
      • Calculadora HMAC
      • Codificador / Decodificador Base64 y URL
      • Conversor de bases numericas
      • Conversor de Timestamp Unix
      • Conversor de colores
      • Generador de UUIDs
      • Editor de expresiones cron
      • Conversor de unidades
    • Juegos
      • Tres en Raya
      • Nim con Q-Learning
    • Más
      • Método D’Hondt
      • Generador de Contraseñas Seguras
  • Noticias
  • Boletín
  • Contacto
  • Tienda
    • Libros
    • Equipamiento de oficina
    • Equipamiento en movilidad

Analytics Lane

Ciencia e ingeniería de datos aplicada

  • Ciencia de datos
  • Machine Learning
  • IA Generativa
  • Python
  • Pandas
  • NumPy
  • R
  • 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

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.

Shallow copy vs Deep copy en Python: la mutación inesperada
En Analytics Lane
Shallow copy vs Deep copy en Python: la mutación inesperada

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

        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.

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.

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

  • Shallow copy vs Deep copy en Python: la mutación inesperada
  • Cómo Proyectar Cuándo Alcanzarás la Independencia Financiera
  • Analytics Lane lanza la versión 1.5 del laboratorio con un extractor de tickets por OCR y consultas SQL sobre CSV en el navegador
  • Cómo Saber si una Diferencia Significativa es Importante
  • Curiosidad: “Wi-Fi” no significa “Wireless Fidelity”
  • Cómo Explorar un Dataset antes de Modelar
  • Cómo Elegir el Test de Hipótesis Correcto para tus Datos
  • Tuplas vs Listas en Python: parecen lo mismo, pero no
  • Guía Completa para Usar el Panda Planner: Tu Camino hacia la Productividad y el Bienestar

Publicidad

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

Guía Completa para Usar el Panda Planner: Tu Camino hacia la Productividad y el Bienestar

noviembre 19, 2026 Por Daniel Rodríguez

Noticias

Analytics Lane lanza la versión 1.5 del laboratorio con un extractor de tickets por OCR y consultas SQL sobre CSV en el navegador

noviembre 18, 2026 Por Daniel Rodríguez

Cómo Explorar un Dataset antes de Modelar

noviembre 17, 2026 Por Daniel Rodríguez

Publicidad

Es tendencia

  • Solución al error Failed to download metadata for repo ‘AppStream’ en CentOS 8 publicado el septiembre 13, 2023 | en Herramientas
  • Curiosidad: El uso del número 42 para fijar la semilla publicado el julio 7, 2023 | en Opinión
  • Método de Brent e implementación en Python publicado el abril 28, 2023 | en Ciencia de datos
  • Exactitud, precisión, recall… qué mide realmente cada métrica (y qué no) publicado el marzo 3, 2026 | en Ciencia de datos
  • Diagramas de dispersión y gráficos de regresión con Seaborn: Visualización de relaciones entre variables numéricas publicado el julio 20, 2023 | en Python

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.1 (11)

Aplicar el método D’Hondt en Excel

Comentarios recientes

  • Daniel Rodríguez en Curiosidad: La Paradoja de Simpson, o por qué no siempre debes fiarte de los promedios
  • Hatepi en Curiosidad: La Paradoja de Simpson, o por qué no siempre debes fiarte de los promedios
  • Daniel Rodríguez en Los récords con asterisco, o la épica del titular sin contexto – El bestiario de los indicadores económicos absurdos (parte 8 y final)
  • Juan en Los récords con asterisco, o la épica del titular sin contexto – El bestiario de los indicadores económicos absurdos (parte 8 y final)
  • bif en JSON en bases de datos: cuándo es buena idea y cuándo no

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