Cómo configurar los documentos del proyecto Python para lograr el éxito

Hola, les saluda Luis y en esta ocasión les traigo este nuevo post.

Automatice el flujo de trabajo de creación de documentos con Sphinx y lea los documentos

Hiciste una increíble pieza de software para Python y la lanzaste al público. ¡Genial! Desafortunadamente, eso no es suficiente. ¡Necesitas documentación!

La buena documentación es vital para la adopción. Hacer documentos claros es una de las cosas más agradables que puedes hacer para tus actuales y futuros usuarios de paquetes. 🎁

Los doctores no se escriben solos, pero puedes llegar a parte con «Lee los documentos», «Esfinge» y algunas lágrimas. 😢 Es broma, puede haber algunas complicaciones, pero con suerte, no habrá lágrimas.

Configurar los documentos para que se construyan automáticamente en cada nueva versión puede ser confuso. En este artículo, te mostraré cómo configurar tus documentos para que puedas darle a tu proyecto la mejor oportunidad de éxito. ¡Vamos a ello! 🚀

Si no tiene un paquete Python básico que funcione, infórmese para aprender cómo agregar pruebas, Travis, Coveralls, Black y PyUp para que tenga más fe en que su código no se romperá.

El proyecto de ejemplo que usaré en este artículo es bibliotecas, un contenedor que hice para la API libraries.io. Puede usarlo para suscribirse a alertas por correo electrónico para nuevas versiones de paquetes de código abierto. También puede usarlo para encontrar información sobre muchos aspectos de paquetes y repositorios de código abierto. aquí son los docs. ¡Veamos cómo construirlos! 🚀

Paso 1: configurar Leer los documentos

¡Lea los documentos de proyectos de código abierto de los hosts de Docs (RTD) de forma gratuita! Es muy genial. 🕶

Configure su cuenta de Read the Docs en https://readthedocs.org.

Luego haz lo siguiente:

1. Importe su repositorio de GitHub manualmente si no lo ve en la lista como disponible para acceder en RTD.
2. Una vez que esté en su proyecto en RTD, ingrese la información relevante y marque la casilla para Editar opciones avanzadas del proyecto.
3. En la siguiente pantalla, elija Python como su lenguaje de programación.
4. Haga clic en Finalizar. Luego Admin. Luego, Configuración avanzada.
5. Marque la casilla para Instalar su proyecto dentro de un virtualenv usando setup.py install e ingrese requirements_dev.txt en el campo Archivo de requisitos (asumiendo que ese es el nombre de su archivo de requisitos. Guardar. Alternativamente, puede crear un archivo de configuración readthedocs.yml como se explica aquí.

6. Haga clic en la pestaña Construcciones. Debería ver que una compilación está en progreso o completada.

7. Cuando se complete la compilación, haga clic en Ver documentos. Estos documentos aún no muestran mucha información específica de nuestro paquete; trabajaremos en eso en un momento.

Cuando empuja a GitHub, sus documentos se compilarán automáticamente si se configura un webhoook. Si conectó automáticamente su repositorio a GitHub, es posible que no necesite configurar nada más para las compilaciones automáticas. ☝️

Si importó manualmente su repositorio, deberá configurar un webhook. Se pueden encontrar instrucciones aquí. Hice pequeñas mejoras en estos documentos, así que si cree que algo no está claro, mejórelos con un PR. 😄 Aquí se explica cómo agregar un webhook:

En su repositorio de GitHub, vaya a Configuración -> Webhooks -> Agregar webhook. Debería ver un formulario como el siguiente.

Para la URL de carga útil, vaya a la configuración de Integraciones de RTD y copie la información del webhook. Anteponerlo con https://. Puede dejar todo lo demás solo y hacer clic en Agregar webhook. O elija Permítame seleccionar eventos individuales si desea activar las compilaciones de documentos RTD en respuesta a otros eventos de GitHub más allá de los empujes al repositorio. Para su información, tuve que eliminar mi webhook en RTD y GitHub y rehacer y volver a agregar el webhook para que funcione.

La próxima vez que envíe su código a GitHub y combine el PR, diríjase a RTD. ¡Debería ver que sus documentos se reconstruyeron automáticamente! 🎉 Espere unos minutos si no ve cambios de inmediato.

¡Genial! Ahora configuremos Sphinx para generar nuestros documentos para RTD.

Paso 2: instalar y configurar Sphinx

Sphinx pretende facilitar la creación de documentos Python inteligentes y atractivos. No sé si diría que es muy fácil, pero Sphinx es genial. 😉 Las características incluyen resaltado de sintaxis, temas y fácil vinculación de documentos. Aquí está la guía de introducción a la Esfinge como referencia.

Añadir sphinx==3.03 a requirements_dev.txt e instálelo con pip install -r requirements_dev.txt.

Crea un directorio de documentos en el nivel superior del directorio de tu proyecto. En ese directorio, ejecuta sphinx-quickstart desde la línea de comando.

Se le harán algunas preguntas. Ingrese el nombre del proyecto y el nombre del autor cuando se le solicite. Generalmente, los valores predeterminados son los que desea.

Los siguientes archivos se generarán automáticamente:

Conf.py

conf.py controla cómo se ejecuta Sphinx cuando se compilan los documentos. En él, configura los ajustes de la documentación del proyecto. Hagamos algunos cambios en conf.py para que Sphinx cree mejores documentos. Descomente y ajuste la sección para que la ruta absurda sea ..

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

Inserte lo siguiente en la lista de extensiones:

extensions = [
'sphinx.ext.napoleon',
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
'sphinx.ext.coverage',
]

No soy fanático de la plantilla de alabastro, así que agregué sphinx_rtd_theme==0.4.3 a mi archivo Requirement_dev.py y lo instalé.

Si hace lo mismo, cambie la línea sobre html_theme en conf.py a esto:

html_theme = ‘sphinx_rtd_theme’

Make

Make es una herramienta de automatización de compilación. El Makefile que fue generado por Sphinx controla cómo los comandos de atajo que comienzan con make funcionar. Más información sobre archivos MAKE aquí. Probablemente pueda arreglárselas sin profundizar en Make. 😉

correr make html desde la línea de comandos para crear sus documentos con este comando de acceso directo. Luego, en su directorio docs-> build _-> html debería ver index.html. Abra el archivo en su navegador y debería ver sus documentos básicos. 😄

Para verificar si hay funciones y clases no documentadas, agregue las siguientes líneas a su Makefile.

%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -b coverage

La línea-b coverage adjunto crea un informe de cobertura para que pueda decirle cuánto de su código está documentado. Ahora cuando corres make html, la carpeta html contendrá un archivo de texto llamado python.txt. Eso le mostrará dónde necesita documentación. 😀

Confirme y continúe para crear sus archivos doc.

Paso 3: crear archivos de documento

Puede elegir si desea escribir sus archivos en Markdown (en adelante md) o reStructuredText (en adelante, en primer lugar). Md está más cerca de la prosa regular y más rápido de aprender. Sin embargo, primero le permite utilizar más de las poderosas funciones de Sphinx. Aquí está la guía de GitHub para md y aquí está la guía de la Esfinge a la primera.

Es su decisión si invierte el tiempo en aprender primero. Hay alrededor de mil millones de otras cosas que podrías aprender, así que si no está en la parte superior de tu lista, lo entiendo. 😉 Sin embargo, muchos documentos del proyecto están escritos en primer lugar, por lo que es bueno saberlo.

Puede convertir entre fragmentos de md y primero rápidamente con esto en línea pandoc convertidor. Puede usarlo para copiar y pegar de un formato a otro. CloudConvert hace lo mismo con archivos completos. CloudConvert comienza a cargarse después de 25 minutos de uso por día. ☝️

Si va por la primera ruta, cambie la extensión de archivo README a .rst.

Además, setup.py necesitará que el nombre README y long_description_content_type cambien a primero.

Voy a usar primero. Si está utilizando md, cambie las siguientes extensiones de archivo a .md.

Cree los siguientes archivos:

1. CODE_OF_CONDUCT.rst
2. CONTRIBUTING.rst
3. HISTORY.rst
4. README.rst

CODE_OF_CONDUCT.rst

Aquí está la información de GitHub con un modelo de código de conducta. El código de conducta explica cómo se espera que las personas se comporten con respecto a la colaboración en su proyecto y qué hacer si las personas no actúan de manera adecuada. Agregue su correo electrónico donde la plantilla tenga un lugar. Si desea copiar la plantilla de rebajas de GitHub en primer lugar, puede usar uno de los convertidores mencionados anteriormente. 😀

CONTRIBUTING.rst

Facilítelo a las personas que quieran contribuir a su proyecto. Incluya instrucciones claras en su archivo de contribución. Siéntete libre de usar mi archivo como base.

HISTORY.rst

El historial contendrá su registro de cambios. Es útil para los usuarios de paquetes. También puede usar el contenido de la información de su lanzamiento en GitHub. ☝️

En history.rst agregue lo siguiente.

=======
History
=======0.0.1 (2020–05–15)
— — — — — — — — -* First release on PyPI.

Actualice la fecha a la fecha apropiada y agregue cualquier otro punto relevante. Agregará el archivo a medida que publique nuevas versiones de su paquete.

README.rst

Su README debe incluir información de instalación y uso básico. Le sugiero que indique a los usuarios los documentos completos sobre RTD. 👉

Puede agregar otros documentos a su proyecto, pero asegúrese de poner los nombres de los archivos en la tabla de contenido de su index.rst. Luego, aparecerán y se vincularán en sus documentos compilados. 😀

Ahora asegurémonos de que nuestros usuarios puedan obtener ayuda para comprender qué hacen sus funciones y clases.

Paso 4: agrega cadenas de documentos

Las cadenas de documentos son un método para comunicarle al usuario cómo funciona una clase o función. Las cadenas de documentos aparecerán en el código de sus usuarios cuando soliciten ayuda. Sphinx tomará sus cadenas de documentos y las hará automáticamente utilizables en sus documentos en RTD también. 👍

Escribe tu Docstrings en su código, inmediatamente después de la primera línea de su clase o función. Las cadenas de documentos comienzan con comillas triples y deben incluir cualquier información que su usuario pueda necesitar, incluida información sobre parámetros y valores de retorno.

Python no tiene una forma obvia para formatear cadenas de documentos. Elija una forma de escribir cadenas de documentos para que se vean ordenadas y nadie tenga que preguntar o pensar en cómo hacer las cosas. 😀

Sugiero usar Estilo de Google – que se recomienda para facilitar la escritura y la lectura. Se puede encontrar una buena discusión sobre el formato de cadenas de documentos aquí.

Asegúrese de informar a sus colaboradores sobre el formato de cadena de documentos que eligió al incluir instrucciones en su archivo de contribución. ☝️

Cuando tenga cadenas de documentos en su código, puede crear sus documentos localmente y ver sus cadenas de documentos en su navegador. Cuando la versión local se vea bien, confirme, presione y combine su PR para ver sus cadenas de documentos en RTD en la página de su módulo.

Si las cosas no funcionan como se esperaba, aquí hay algunas sugerencias para que vuelva a encarrilarse:

Solución de edición

Sphinx y RTD pueden romperse o hacer que los documentos se vean diferentes de lo esperado por muchas razones. Consulte los registros de compilación en RTD para encontrar errores.

Los problemas comunes incluyen:

• Si sus documentos no están compilando y está usando los primeros archivos, es probable que haya un primer archivo inválido en alguna parte. Para encontrar primero que no es válido, ejecute el contenido del archivo a través de uno de los primeros comprobadores mencionados anteriormente.
• Si sus documentos se compilan pero sus módulos no se muestran, consulte los registros de salida sin procesar en RTD para obtener sugerencias.
• Asegúrese de que los archivos setup.py y requirements_dev.txt sean correctos.
• Si necesita una variable de entorno para que las cosas se ejecuten, agréguela en la configuración de RTD.

Los documentos de RTD y Sphinx y Stack Overflow son útiles, pero esta solución de problemas me resulta engorrosa. Siento tu dolor. 🙁

Ahora veamos un tema más agradable: comunicar información a los posibles usuarios a través de insignias.

Paso 5: agregue insignias al archivo README

Las insignias brindan información de un vistazo a las personas interesadas en su proyecto. Las insignias pueden infundir confianza y legitimidad. A continuación, se muestra un ejemplo de las insignias que pueden colocarse encima de su archivo README:

Hay muchas insignias disponibles en https://shields.io/ y https://badgen.net/. Agregué algunos de los míos de shields.io. Para obtener el código de la insignia, no solo copie la URL junto a la insignia. Haga clic en la URL. Luego agregue el nombre de su paquete. Vea el ejemplo a continuación para la insignia de la rueda.

Luego copie el código md o el primer código del menú desplegable y péguelo en su archivo README.

Hay muchas insignias disponibles en el sitio web de la aplicación correspondiente. PyUp, Travis y Coveralls tienen un código de placa que puede obtener. Para PyUp, si hace clic en la insignia en su panel de PyUp, verá el código que puede copiar e incrustar en su archivo README.

Aquí está Información de RTD sobre insignias.

¡Genial! Tenemos una insignia. Finalmente, veamos cómo facilitar la colaboración.

Paso 6: crear plantillas de problemas y relaciones públicas

La ayuda de la comunidad en general es un gran beneficio disponible para un proyecto de código abierto. Desea que sea fácil para sus usuarios informar errores y solicitudes de funciones con información relevante. Un gran primer paso es proporcionar una plantilla clara de problemas.

Plantillas de edición

En su navegador, vaya a su repositorio de GitHub -> Configuración -> Opciones. En Funciones, haga clic en el botón verde Configurar plantillas.

Puede agregar una plantilla de problema personalizada o usar una de las plantillas predeterminadas de GitHub.

Las plantillas de solicitud de extracción son igualmente útiles. GitHub tiene una buena guía para hacer uno aquí.

¡Ahora le resultará más fácil obtener ayuda con su proyecto de código abierto!

Conclusión

En este artículo, aprendió a crear excelentes documentos que se compilan automáticamente. También aprendió a transmitir información de un vistazo con insignias. Finalmente, viste cómo puedes lograr atraer colaboradores.

Ahora la gente sabrá cómo utilizar y contribuir a su paquete. ¡Increíble! 🎉

Espero que esta guía le haya resultado útil. Si lo hizo, compártelo en sus canales de redes sociales favoritos para que otros también puedan encontrarlo. 👍

---