Agrega un archivo README a tu paquete de Python#
En las lecciones anteriores aprendiste:
Objetivos de aprendizaje
En esta lección aprenderas:
Cómo agregar un archivo README.md a tu paquete.
Cuáles son los elementos principales de un archivo README.md.
¿Qué es un archivo README?#
El archivo README.md es el README del proyecto y se encuentra en la raíz del directorio de tu proyecto. Ayuda a que una persona entienda:
El nombre de tu paquete
Qué hace el paquete. Tu archivo README debe indicar claramente el/los problema(s) que tu software está diseñado para resolver y su público objetivo.
El «estado» actual de desarrollo del paquete (mediante badges)
Cómo comenzar a usar tu paquete.
Cómo contribuir a tu paquete
Cómo citar tu paquete
Tu archivo README.md es importante porque suele ser lo primero que alguien ve antes de instalar tu paquete. El archivo README también se utiliza para generar tu página principal en PyPI.
Ten en cuenta que no existe una estructura de contenido específica para los archivos README. Sin embargo, este tutorial describe las secciones que te sugerimos incluir en tu archivo README.
Crear un archivo README.md para tu paquete#
Es momento de agregar un archivo README.md a tu directorio de proyecto.
Paso 0: Crear un archivo README#
Para comenzar, si aún no tienes un archivo README.md en tu directorio de proyecto, créalo.»
Truco
Si creaste tu directorio de proyecto a partir de
un repositorio de GitHub en línea
usando
hatch init
Entonces es posible que ya tengas un archivo README.MD en tu directorio de proyecto.
Paso 1: Agregar el nombre de tu paquete como título del README#
En la parte superior del archivo README.md, agrega el nombre de tu paquete.
Si estás usando markdown, debe ser un encabezado de nivel 1 (H1), que se indica con un solo símbolo #.
# Título-del-paquete-aquí
Paso 2: agregar insignias (badges) en la parte superior de tu archivo README#
Es común que quienes mantienen proyectos agreguen insignias en la parte superior de sus archivos README. Las insignias te permiten a ti y a las personas usuarias de tu paquete monitorear cosas como:
Documentación rota y compilaciones de prueba fallidas
Versiones de tu paquete disponibles en PyPI y conda.
Si tu paquete ha sido revisado y validado por una organización como pyOpenSci y/o JOSS.
Si ya has publicado tu paquete en pypi.org, puedes usar shields.io para crear una insignia de versión del paquete. Esta insignia se actualizará dinámicamente a medida que publiques nuevas versiones de tu paquete en PyPI.
Si no, puedes dejar esta parte superior vacía por ahora y agregar insignias a tu README más adelante cuando tenga sentido hacerlo.
Paso 3: Agregar una descripción de lo que hace tu paquete#
Debajo de las insignias (si las tienes), agrega una sección de texto que proporcione una descripción clara y fácil de entender de lo que hace tu paquete.
Mantén esta sección breve.
Intenta evitar la jerga técnica.
Define los términos técnicos que utilices para que la descripción sea accesible a más personas.
Recuerda que cuanto más personas entiendan lo que hace tu paquete, más personas lo utilizarán.
Paso 4: Agregar instrucciones de instalación del paquete#
Luego, agrega instrucciones que indiquen a las personas cómo instalar tu paquete.
Por ejemplo, ¿pueden usar pip para instalar tu paquete? python -m pip install nombre_del_paquete
¿o conda?
conda install -c conda-forge nombre_del_paquete.
Si aún no has publicado tu paquete en pypi.org, puedes omitir esta sección y volver más adelante para agregar estas instrucciones.
Paso 5: Configuración adicional#
En algunos casos, quienes usen tu paquete pueden necesitar instalar otras herramientas manualmente para poder utilizarlo. Si ese es el caso, asegúrate de agregar una sección de configuración adicional en tu archivo README.
Aquí, documenta brevemente (o enlaza a la documentación) cualquier configuración adicional necesaria para usar tu paquete. Esto podría incluir:
información de autenticación, si aplica a tu paquete.
instalación de herramientas adicionales, como GDAL.
Nota
Muchos paquetes no necesitarán una sección de configuración adicional en su README. En ese caso, puedes omitir esta sección.
Paso 6: Agregar una sección de inicio rápido#
A continuación, agrega una sección de inicio rápido. Dentro de esta sección, incluye un pequeño ejemplo de código que demuestre cómo importar y utilizar algunas de las funcionalidades de tu paquete.
Proporciona un ejemplo de código completamente funcional si es posible
Es importante intentar que los ejemplos de código que proporcionas a las personas usuarias sean lo más útiles posible.
Asegúrate de proporcionar un ejemplo de código que se pueda copiar y pegar y que funcione tal cual en un Jupyter Notebook o archivo .py, si es posible.
Si se requieren tokens u otros pasos para ejecutar tu paquete, asegúrate de ser claro acerca de cuáles son esos pasos.
Para pyosPackage, una breve demostración de inicio rápido podría verse así:
>>> from pyospackage.add_numbers import add_num
>>> add_num(1, 2)
3
O también puede ser simplemente un enlace a un tutorial de inicio que hayas creado. Si aún no lo tienes, puedes dejarlo vacío por el momento.
Este también es un excelente lugar para agregar enlaces a tutoriales que ayuden a las personas usuarias a entender cómo usar tu paquete en flujos de trabajo comunes.
Paso 7: Sección de comunidad#
La sección de comunidad de tu archivo README es un lugar para incluir información para personas usuarias que quieran interactuar con tu proyecto. Esta interacción probablemente ocurrirá en una plataforma como GitHub o GitLab.
En la sección de comunidad, agregarás enlaces a tu guía de contribución y al CODE_OF_CONDUCT.md. Crearás un archivo de código de conducta en la siguiente lección.
A medida que tu paquete crezca, también podrías agregar un enlace a una guía de desarrollo que sigan las personas colaboradoras y el equipo de mantenimiento. La guía de desarrollo describe cómo realizar tareas de mantenimiento como:
ejecutar pruebas
publicar versiones del paquete
generar documentación
y más.
Paso 8: Información de citación#
Finalmente, es importante indicar a las personas usuarias cómo citar tu paquete. Puedes comunicar la información de citación de varias maneras.
Puedes usar una herramienta como Zenodo para crear un DOI y la información de citación asociada a tu paquete, si está alojado en una plataforma como GitHub. Consulta este breve tutorial: https://coderefinery.github.io/github-without-command-line/doi/
Alternativamente, puedes enviar tu paquete a un proceso de revisión por pares como el de pyOpenSci: https://www.pyopensci.org/about-peer-review/index.html. Después de ser aceptado por pyOpenSci, si tu paquete está dentro del alcance, puedes ser aceptado por el Journal of Open Source Software y obtener un DOI mediante su sistema de Crossref gracias a esta colaboración: https://www.pyopensci.org/about-peer-review/index.html
El archivo README final#
Tu archivo README.md final debería verse similar a esto:
# pyosPackage
[](https://doi.org/10.5281/zenodo.8365068)
[](https://github.com/pyOpenSci/software-submission/issues/115)
## What pyosPackage does
Short description here using non-technical language that describes what your package does.
## How to install pyosPackage
:::{todo}
- when i add more to the pyos package this can use that readme>
:::
To install this package run:
`python -m pip install pyosPackage`
## OPTIONAL - if you have additional setup instructions add them here. If not, skip this section.
## Get started using pyosPackage
Here add a quick code demo showing a user how to use the package after it is installed.
```python
>>> from pyospackage.add_numbers import add_num
>>> add_num(1, 2)
3
```
You can also add any links to tutorials in your documentation here.
## Community
Add information here about contributing to your package. Be sure to add links to your
`CODE_OF_CONDUCT.md` file and your development guide. For now this section might be
empty. You can go back and fill it in later.
## How to cite pyosPackage
citation information here
Conclusión#
Es importante considerar qué información podría necesitar una persona usuaria o colaboradora nueva al crear tu archivo README.md. Aunque no existe una plantilla perfecta, lo anterior es un conjunto de recomendaciones para empezar. Es posible que necesites agregar otros elementos a este archivo a medida que tu paquete evolucione y la comunidad comience a utilizarlo.
En la siguiente lección, agregarás un archivo LICENSE a tu paquete de Python. Este archivo es fundamental, ya que indica a las personas usuarias cómo pueden (y no pueden) usar legalmente tu paquete. Además:
Genera confianza en las personas usuarias
Desincentiva el uso indebido de tu paquete y su código asociado