Documentación para tu Paquete de Python de Código Abierto#
Importante
Ten en cuenta que las herramientas que se discuten aquí son las que vemos que se usan comúnmente en la comunidad. A medida que las herramientas evolucionen, actualizaremos esta guía. Si estás enviando un paquete para la revisión por pares de pyOpenSci y usas otras herramientas que no están en nuestra guía para construir tu paquete, ¡aún puedes enviarlo para su revisión! Las herramientas enumeradas aquí son sugerencias, no requisitos. Nuestros requisitos se centran en el contenido de la documentación de tu paquete.
La documentación es fundamental para el éxito de tu paquete de Python#
La documentación es tan importante para el éxito de tu paquete de Python de código abierto como el propio código.
La calidad del código es, por supuesto, valiosa, ya que es la forma en que tu paquete realiza las tareas. Sin embargo, si los usuarios no entienden cómo usar tu paquete en sus flujos de trabajo, no lo usarán.
Además, documentar explícitamente cómo contribuir es importante si deseas construir una base de colaboradores para tu paquete.
Dos tipos de usuarios de paquetes de Python#
La documentación que escribas para tu paquete debe dirigirse a dos tipos de usuarios:
1. Basic Tool Users#
Los Usuarios Básicos de la Herramienta son las personas que usarán el código de tu paquete en sus flujos de trabajo de Python. Pueden ser nuevos (o principiantes) en Python y/o en la ciencia de datos. O programadores expertos. Pero puede que no tengan experiencia en desarrollo de software. Estos usuarios necesitan saber:
Cómo instalar tu paquete
Cómo instalar las dependencias que requiere tu paquete
Cómo empezar a usar la base de código
Información sobre cómo citar tu código / darte crédito si lo están usando en una aplicación de investigación.
Información sobre la licencia que utiliza tu código para que sepan cómo pueden o no pueden usar el código en un entorno operativo.
2. Potential tool contributors#
El otro grupo de usuarios tiene más experiencia y/o está más involucrado con tu paquete. Ellos como tal, son colaboradores potenciales. Estos usuarios:
pueden tener experiencia en desarrollo de software,
también podrían contribuir con correcciones de errores a tu paquete o actualizaciones a tu documentación
también podrían ser simplemente usuarios que encontrarán errores de ortografía en tu documentación o errores en tus tutoriales.
Estos usuarios necesitan todo lo que un usuario básico necesita. Pero también necesitan entender cómo te gustaría que contribuyeran a tu paquete. Estos colaboradores potenciales necesitan:
Una guía de desarrollo para ayudarles a entender la infraestructura utilizada en el repositorio de tu paquete.
Directrices de contribución que aclaren los tipos de contribuciones que aceptas y cómo prefieres que se envíen esas contribuciones.
Importante
Es importante recordar que la definición de lo que es una contribución puede ser amplia. Una contribución podría ser algo tan simple como un informe de error. O corregir un problema de ortografía en tu documentación. O podría ser una corrección de código que incluye una nueva prueba que cubre un caso límite que descubrieron.
Elementos de documentación que pyOpenSci busca al revisar un paquete de Python#
En la revisión abierta por pares de pyOpenSci, buscamos una estructura de documentación que apoye tanto a los usuarios de tu herramienta como a los colaboradores potenciales. Los archivos y elementos que buscamos específicamente se pueden encontrar en nuestra lista de verificación de revisión por pares (ver enlace a continuación).
En esta guía, discutimos cada elemento requerido y también discutimos otros elementos que deberías considerar en la documentación de tu paquete con más detalle.
Ver la lista de verificación de la revisión por pares de pyOpenSci
Un ejemplo del repositorio de GitHub de MovingPandas con todos los archivos principales, incluyendo CONTRIBUTING.md, README.md, CODE_OF_CONDUCT.md y un archivo LICENSE.txt. (captura de pantalla tomada el 23 de noviembre de 2022)#
¿Qué sigue en esta sección de documentación de paquetes de Python?#
En esta sección de la guía de paquetes de pyOpenSci, te guiaremos a través de las mejores prácticas para configurar la documentación de tu paquete de Python. También te sugeriremos herramientas que puedes usar para construir el sitio web de documentación orientado al usuario.