Anuncio de ribbity: un proyecto hacky para crear sitios web a partir de rastreadores de problemas de GitHub

lun 23 mayo 2022

Por C. Titus Brown

en programacion

etiquetas: github

Durante las últimas semanas, he estado hackeando un nuevo microproyecto de pasión, cuyo nombre en código es ribbity.

ribbity es el software que construye el sitio web de ejemplos sourmashal producir un mkdocs sitio de la rastreador de problemas de ejemplos sourmash.

En resumen, ribbity toma las descripciones de los problemas de GitHub y las coloca en los archivos Markdown para que pueda ejecutar mkdocs :).

Puede ver la documentación de instalación y configuración de ribbity aquí.

¿Por qué, oh, por qué harías esto?

Bien podría preguntarse… ¿por qué no «simplemente crear un sitio de Markdown», tal vez con solicitudes de incorporación de cambios? Algunas razones –

El rastreador de problemas de GitHub es increíble

Primero, me gusta mucho usar los rastreadores de problemas de GitHub para organizar recursos y notas. por ejemplo, el rastreador de problemas sourmash es mi «cerebro externo» para todo lo relacionado con la comparación de genomas y sourmash. También tengo varios repositorios privados que utilizo para organizar colecciones de enlaces.

Más específicamente, me encanta la función de «vínculos de retroceso» de github (donde cuando te refieres al problema A desde el problema B, el problema A recibe un puntero al problema B) – esto estaba en el original Proyecto Xanadú plan para documentos de hipertexto interconectados, pero en realidad nunca llegó a la Web. Es terriblemente útil.

¡Aquí, la capacidad de ver vínculos de retroceso de repositorios privados en repositorios públicos es particularmente encantadora!

Organización y comentarios flexibles

También me gusta mucho la funcionalidad de etiquetado (categorización) y comentarios de github.

Además, github tiene una muy buena compatibilidad con Markdown, junto con un editor utilizable. Y, aunque escribir Markdown en un navegador web no es mi actividad favorita, seguro que es bueno poder hacerlo en un apuro. Pero lo que es más importante, puedo escribir Markdown en una página hackmd y luego copiarlo/pegarlo en un problema de github: este es un flujo de trabajo cada vez más común ¡para mi!

Autenticación y notificaciones flexibles

Realmente me gustan (y uso mucho) los sistemas de autenticación y notificación de github. Puede habilitar y deshabilitar el acceso a los repositorios, ver problemas específicos y silenciar a otros, bloquear problemas, bloquear personas para que no publiquen, etc., etc.

Necesito autenticación y notificaciones, pero no estoy interesado en hacer nada de eso yo mismo. Construir sobre todo eso es una buena simplificación.

GitHub como plataforma

De manera más general, me gusta mucho cómo GitHub se está convirtiendo en una plataforma para cosas; puede ver un proyecto mío anterior aquí, Uso de GitHub para informes de proyectos janky: algo de código.

Otros proyectos inspiradores en este espacio incluyen utteranc.es, que construye una plataforma de comentarios de blog sobre github; y La «gestión de proyectos de baja fricción» de Coraline sitio. Y, aunque no uso específicamente conjunto de datos (sin embargo) de cualquier manera, ha sido un importante contribuyente conceptual a la idea de que alojar cosas estáticamente es una gran idea :).

(Si conoce otros hacks basados ​​en github como este, déjelos en los comentarios o ¡hazme un ping en Twitter!)

El alojamiento del sitio estático mkdocs es simple, especialmente a través de las páginas de github

mkdocs produce sitios estáticos, ¡y los sitios estáticos son impresionantes! (inspiración de conjunto de datos aquí, de nuevo.) No hay bases de datos complicadas, ni autenticación, ni desagradables JavaScripts que se arrastran por mis páginas. (Nota al margen: no conozco JavaScript).

Además, las páginas de github son fáciles (y mkdocs admite de forma nativa la implementación en páginas de github de forma nativa).

Y, por supuesto, puede alojar sitios mkdocs en muchos lugares. Por lo tanto, es bastante flexible y permite construir sobre mkdocs.

Pero, ¿permite algo genial?

Una de las principales motivaciones proximales para construir ribbity fue la complejidad creciente de la documentación sourmashque corre peligro de volverse extenso y laberíntico.

Me gusta mucho la idea de un conjunto de documentación que está explícitamente destinado a ser explorado y buscado de forma no lineal.

Así es como uso los problemas de github en la práctica.

Así que parecía natural probar algo nuevo que eliminara parte de la complejidad de la interfaz de github y la hiciera personalizable.

Y estoy bastante contento con el resultado. ejemplos de puré de azúcar ¡Sitio web!

En particular, realmente ha reducido la barrera de la contribución para mí, personalmente. No tengo que preocuparme por las solicitudes de incorporación de cambios o la integración de nuevos ejemplos en un sitio de documentos grande y complicado en el buen sentido: simplemente lanzo un nuevo ejemplo, le pongo algunas etiquetas y sigo con mi día.

En algunos aspectos, esta es una versión de el truco de la solicitud de extracción, un modelo de aporte que siempre me ha intrigado. Excepto que en lugar de otorgar acceso de relaciones públicas a los contribuyentes, solo necesitan poder agregar problemas, lo que, de manera predeterminada, ¡cualquiera puede hacer en cualquier proyecto visible de GitHub!

¿Cómo se implementa la ribbity?

Es bastante simple debajo –

  1. «tirar» de los problemas de GitHub a un volcado de pickle de Python.
  2. procesa el volcado de pickle en objetos de Python, salado con algunas expresiones regulares.
  3. ejecutar el modelo de objeto a través de la plantilla jinja2 para construir un docs/ directorio.
  4. alimento docs/ directorio en mkdocs, que construye un site/ directorio.

He superpuesto algunas pruebas y algunas cosas del paquete de Python y algo de CLI, pero el código central es agradablemente simple: menos de 400 líneas de código, incluidos espacios y comentarios.

¿Dónde está la costilla?

Algunas personas han mirado a Ribbity y se han ido… guau. ¡Quiero eso! ¡Así que eso es bueno y validador!

En particular, ha habido cierto entusiasmo entre los colegas por tener una interfaz diferente a los rastreadores de problemas de github. ¡Una motivación específica es que la búsqueda receptiva que ofrece la interfaz mkdocs predeterminada es agradable! Y pude ver un argumento para agregar varios rastreadores de problemas en un solo sitio, que es un caso de uso en el que algunos colegas están interesados.

Básicamente, veo mucho entusiasmo en torno a la piratería específica y personalizable de las cosas de github.

Pero… no sé. Hay bastante espacio entre un mínimo «¡esto es útil! y lo suficientemente limitado como para que podamos mantenerlo funcionando». y una versión defectuosa y mal reimplementada de todo lo que ya ofrece el sitio web de github. Me inclino más por lo primero, porque creo que se puede lograr y ofrece una utilidad específica. Pero también tengo muchas ideas sobre cómo hacer cosas parecidas a ribbity en otras direcciones (¡Mira este espacio!)

Si tuviera que adivinar, creo que mi interés personal en ribbity evolucionará de las siguientes maneras:

  • Trabajaré para impulsar más la funcionalidad de munging de texto de ribbity en jinja2, y hacer que la descarga de github sea una versión más completa (¡y más estandarizada!) del repositorio de problemas.
  • esto, a su vez, hará que el ribbity central sea una combinación simple de (a) plantillas jinja2 superpuestas en (b) un modelo de objeto github.
  • si puedo obtener las primitivas correctamente, esto facilitaría la creación de superposiciones personalizadas en los rastreadores de problemas de github completamente en jinja2.

Y eso en realidad me parece bastante mantenible.

Entonces, la funcionalidad actual de ribbity sería simplemente un conjunto específico de plantillas que usamos para construir un tipo particular de sitio web. Y la nueva funcionalidad o diferentes superposiciones de seguimiento de problemas podrían construirse completamente en jinja2.

¿Pero quién sabe? Definitivamente no me comprometo a nada; solo jugando por ahora.

Habiendo dicho eso, estoy pensando en aplicar ribbity para crear un directorio de recursos de capacitación y lanzarlo al problema del boletín informativo, y un colega lo está usando para su propio sitio de ejemplos. ¡Así que ya veremos!

¿Qué otras experiencias divertidas querías relatar?

Esta fue mi primera experiencia con Clases de datos de Python! ¡Super guay! Código aquí.

(Una colega en el laboratorio, Tessa Pierce, comenzó a usarlos más en agridulcey eso finalmente me motivó a pasar de las tuplas con nombre o directamente a los objetos de Python desnudos).

Esta fue también mi primera experiencia de análisis con TOML, que es bastante agradable! Y encontré el tomli analizador para ser fácil de usar, y pensó que el tomllib PEP fue realmente genial

Pensamientos concluyentes

costilla es de código abierto – BSD 3-cláusula!

Por favor, presente los problemas si tiene ideas sobre cómo podría querer usar ribbity!

Las solicitudes de extracción son bienvenidas, pero este es un proyecto paralelo, por lo que, a menos que sean bastante mínimas o estén acompañadas de pruebas buenas, claras y obvias, podría diferirlas como «se necesita demasiado cerebro». Animo a la bifurcación y la experimentación!

¡Tus pensamientos son bienvenidos!

–tito



Fuente del artículo

Deja un comentario