21 Hacer un repositorio navegable en GitHub

La eficacia irracional de la navegabilidad de GitHub. Uno de los aspectos favoritos de GitHub es la capacidad de inspeccionar los archivos de un repositorio en un navegador. Ciertas prácticas hacen que la navegación sea más gratificante y pueden posponer el día en que debe crear un sitio web adecuado para un proyecto. Quizás indefinidamente.

21.1 Conozca sus archivos

Guarde los archivos en el formato más sencillo y amigable con la web que sea compatible con sus objetivos principales. El texto plano es el mejor. GitHub ofrece un manejo especial para ciertos tipos de archivos:

  • Archivos Markdown, que pueden estar destinados a la conversión en, por ejemplo, HTML
  • Archivos Markdown llamados README.md
  • Archivos HTML, a menudo resultado de la compilación de archivos Markdown
  • Código fuente, tales como los archivos .R
  • Archivos delimitados, como CSVs y TSVs
  • Archivos PNG

21.2 Traiga sus archivos complicados: haciendo commit a productos derivados

Hay que reconocer el malestar que algunas personas sienten al poner los productos derivados bajo control de versiones. Específicamente, si tiene un documento de R Markdown foo.Rmd, puede usar knit() para producir el producto intermedio foo.md, que puede convertirse en la última salida foo.html. ¿Cuáles de esos archivos se les permite “dejar” bajo control de versiones? Los verdaderos defensores de la fuente dirán sólo foo.Rmd, pero los pragmatistas saben que esto puede ser un grave problema en la vida real. El hecho de que pueda reconstruir todo desde cero, no significa que uno quiera hacerlo.

El tabú de mantener productos derivados bajo control de versiones se origina de la compilación de ejecutables binarios de origen. El software construido en un Mac no funcionaría en Windows, por lo que tendría sentido mantener estos binarios fuera del repositorio del código fuente sagrado. Además, podría asumir que las personas con acceso al repositorio tienen la pila de desarrollo completa y aprovechan las oportunidades para usarla. Ninguno de estos argumentos se aplica realmente al flujo de trabajo foo.Rmd -> foo.md -> foo.html. ¡No tenemos que seguir ciegamente las tradiciones del dominio de compilación!

De hecho, ver las diferencias de foo.md o foo-figure-01.png puede ser extremadamente informativo. Esto también es cierto en grandes proyectos de análisis después de una operación make clean; make all. Al mirar las diferencias en los productos posteriores, a menudo captura cambios inesperados. Esto le puede sugerir cambios en los datos subyacentes y/o el comportamiento de los paquetes de los que depende.

Este capítulo explora cosas interesantes que GitHub puede hacer con varios tipos de archivos, si sucede que terminan en su repositorio.

21.3 Markdown

Descubrirá rápidamente que GitHub procesa los archivos de Markdown muy bien. Al hacer clic en foo.md, obtendrá una vista previa decente de foo.html. Yay! Debería leer La propia guía de GitHub sobre cómo aprovechar el compilado automático de Markdown.

Explote esto agresivamente. Haga de Markdown su formato predeterminado para los archivos de texto narrativo y utilícelos generosamente para incrustar notas para usted y otros en un repositorio alojado en Github. Es una manera fácil de obtener pseudo-páginas web dentro de un proyecto “de forma gratuita”. Es posible que ni siquiera compile estos archivos en HTML explícitamente; En muchos casos, la vista previa HTML ofrecida por GitHub es todo lo que necesita.

¿Qué significa esto para los archivos de R Markdown? Mantener el Markdown de nivel intermedio. O sólo compilar a Markdown. Haga commit tanto a foo.Rmd como a foo.md, incluso si elige .gitignore al final foo.html. Desde Septiembre de 2014, GitHub hace que los archivos de R Markdown aparezcan muy bien, como Markdown, y con el resaltado de sintaxis adecuado, lo cual es genial. Pero, por supuesto, los bloques de código sólo se quedan allí sin ejecutar, por lo que el consejo sobre mantener el nivel medio de Markdown todavía se mantiene. Los encabezados YAML deben verse así para el .Rmd:

o como esto para .R:

En RStudio, al editar el .Rmd, haga clic en el engranaje junto a “Knit HTML” para activar la ayuda de creación de YAML. Desde principios de 2016, los archivos rmarkdown ofrecen un formato de salida personalizado para markdown GitHub,github_document. Lea sobre flujos de trabajo con Markdown para obtener ejemplos explícitos de cómo usar esto.

Para un documento rápido y autónomo que no encaja perfectamente en un repositorio o proyecto (aún), haga de él un Gist. Ejemplo: Consejos sobre lo que debe hacer para convertirse en un científico de datos de Hadley Wickham. Los Gists pueden contener varios archivos, por lo que incluso puede proporcionarse el script en R o R Markdown y el Markdown resultante, como se ha hecho en este artículo de Consejos de tabulación cruzada de Twitter.

21.4 README.md

Probablemente ya sepa que GitHub procesa README.md en el nivel superior de su repositorio como la página de destino de facto. Esto es análogo a lo que sucede cuando se apunta un navegador web en un directorio en lugar de una página web específica: si hay un archivo llamado index.html, eso es lo que el servidor le mostrará de forma predeterminada. En GitHub, los archivos llamados README.md juegan exactamente este rol para los directorios de su repositorio.

Implicación: para cualquier grupo lógico de archivos o mini proyecto dentro de su proyecto, cree un subdirectorio en su repositorio. A continuación, cree un archivo README.md para anotar estos archivos, recopilar los enlaces relevantes, etc. Ahora, cuando navegue al subdirectorio de GitHub, aparecerá simplemente el README.md.

Algunos repositorios consisten únicamente en el README.md. Ejemplo: documento de Jeff Leek sobre Cómo compartir datos con un estadístico o Desarrollar paquetes en R. Quizás se convierta en un fan más grande de repositorios de solo README que de los gists porque los repositorios emiten las notificaciones de activación, mientras que los comentarios sobre los gists no lo hacen.

Si tiene un directorio lleno de figuras amigables para la web, como PNG, puede usar código como este para generar un README.md para una galería rápida de bricolaje, como Karl Broman ha hecho con su FruitSnacks. También se ha utilizado este dispositivo para compartir diapositivas de Keynote en GitHub (¡mea culpa!). Exportarlos como imágenes PNG y enviarlos a una galería README: diapositivas en organización de archivos Y algunos en nombre de archivo.

21.5 Encontrando cosas

Pues bien, estos son puros consejos para GitHub, pero si ha llegado tan lejos, obviamente ya es un entusiasta.

  • Pulse t para activar el buscador de archivos siempre que esté en un archivo de repositorio y una vista de directorio. IMPRESIONANTE, especialmente cuando hay archivos escondidos en un montón de subdirectorios.
  • Pulse y para obtener un enlace permanente cuando esté viendo un archivo específico. Mire los cambios en la URL. Esto es importante si está a punto de vincularse a un archivo o a líneas específicas. De lo contrario, sus enlaces se romperán fácilmente en el futuro. Si el archivo se elimina o cambia de nombre o si las líneas se insertan o eliminan, sus vínculos ya no apuntarán a lo que intentó. Use y para obtener enlaces que incluyan un commit específico en la URL.

21.6 HTML

Si tiene un archivo HTML en un repositorio de GitHub, simplemente visitando el archivo, muestra el código HTML crudo. He aquí un ejemplo horrible:

Nadie quiere mirar eso. Puede proporcionar esta URL a rawgit.com para publicar este HTML apropiadamente y obtener una vista previa decente.

Puede formar dos tipos diferentes de URL con rawgit.com:

Este tipo de enlace mejorado podría ser una de las cosas útiles para poner en un README.md u otro archivo de Markdown en el repositorio.

También puede consultar esta extensión de Chrome o GitHub & BitBucket HTML Preview, aunque recientemente se ha tenido más éxito con rawgit.com. (Tampoco trabajar con repositorios privados de GitHub, que es la principal razón para mantener los archivos de Markdown intermedios para HTML, como se describió anteriormente.)

Algunas veces, incluir archivos HTML hará que GitHub piense que su repositorio R es HTML. Además de ser un poco molesto, esto puede hacer que sea difícil para las personas encontrar su trabajo si están buscando específicamente repositorios de R. Puede excluir estos archivos o directorios de las estadísticas de idioma de GitHub mediante la agregación de un archivo .gitattributes que los marque como “documentación” en lugar de código. Vea un ejemplo aquí.

21.7 Código fuente

Notará que GitHub hace resaltado automático de sintaxis para el código fuente. Por ejemplo, observe el color de este R script. La extensión del archivo es el determinante primario de si/cómo se aplicará el resaltado de la sintaxis. Puede ver información sobre idiomas reconocidos, las extensiones predeterminadas y más en github/linguist. Debería hacerlo de todos modos, pero deje que esto sea otra razón para seguir la convención en el uso de las extensiones de archivo.

Tenga en cuenta que puede hacer clic en “Raw” en este contexto, para obtener sólo el texto sin formato y nada más que el texto sin formato.

21.8 Archivos delimitados

GitHub compilará muy bien los datos tabulados en forma de archivos .csv (separados por comas) y .tsv (separados por tabuladores). Puede leer más en la entrada del blog anunciando esta función en agosto de 2013 o en esta página de ayuda de GitHub.

Consejo: ¡Aprovéchelo! Si algo en su repositorio puede ser naturalmente almacenado como datos delimitados, por todos los medios, hágalo. Haga de la coma o tabulado su delimitador predeterminado y utilice los sufijos de archivo que GitHub espera. Se ha notado que en GitHub es más fácil de confundir que R sobre cosas como citar, así que inspeccione siempre el archivo .csv o .tsv compilado por GitHub en el navegador. Es posible que necesite limpiarlo ligeramente para que la representación automática funcione correctamente. Piense en ello como otra forma de aprender sobre las imperfecciones en sus datos. Aquí hay un ejemplo de un archivo delimitado por tabuladores en GitHub: lotr_clean.tsv, originalmente encontrado aquí (no, IBM murió en julio de 2015).

Tenga en cuenta que puede hacer clic en “Raw” en este contexto, así, para obtener sólo el texto sin formato y nada más que el texto sin formato.

21.9 PNGs

PNG es el formato “obvio” en el cual se almacenan las figuras en la web. Pero muchos de nosotros gustamos de un formato vectorial, como PDF, para las figuras de propósito general. En pocas palabras: los PNGs lo harán menos loco que los PDF en GitHub. Para reducir el agravamiento en torno a las figuras de visualización en el navegador, asegúrese de tener una versión PNG en el repositorio.

Ejemplos:

  • Esta figura en PNG sólo aparece en el navegador
  • Una figura diferente almacenada como PDF produce el temido, molesto “View Raw”. Tendrá que hacer clic y, en mi navegador de OS +, esperar a que el PDF aparezca en un visor de PDF externo. Actualización 2015-06-19: desde que se escribió por primera vez este documento, GitHub ha [elevado su tratamiento de PDFs] (https://github.com/blog/1974-pdf-viewing). Es lento pero funciona.

Ojalá que estemos moviéndonos hacia un mundo donde pueda ser “amigable con la web” y “vectorial” al mismo tiempo, sin dolores de cabeza indebidos. Desde octubre de 2014, GitHub ofrece una mejor visualización y difusión de SVGs. Así que no lea este consejo como SVGs desalentadores. ¡Hágalo! Pero considere guardar un PNG como respaldo de emergencia, por ahora.

21.10 Vinculación a un archivo ZIP del repositorio

La navegabilidad de GitHub hace que su trabajo sea accesible para las personas que se preocupan por su contenido, pero que aún no utilizan Git. ¿Y si esa persona quiere todos los archivos? Sí, hay un botón “Descargar ZIP” ofrecido por GitHub. ¿Pero qué hay si usted quiere un link incluido en un email o en otro documento? Si agrega /archive/master.zip al final de la URL de su repositorio, construirá un enlace que descargará un archivo ZIP de su repositorio. Haga clic aquí para probar esto en un repositorio muy pequeño:

https://github.com/jennybc/lotr/archive/master.zip

¡Búsquelo en su carpeta de descargas!

21.11 Enlaces y figuras incrustadas

  • Para vincular otra página en su repositorio, simplemente use un enlace relativo: [admin](courseAdmin/) se vinculará al directorio courseAdmin/ dentro del directorio actual. [admin](/courseAdmin/) se enlazará al directorio courseAdmin/ de nivel superior desde cualquier lugar del repositorio.

  • La misma idea también trabaja para imágenes. ![](image.png) inculirá image.png localizada en el directorio actual

21.12 Permita que la gente lo corrija en internet

¡A ellos les gusta eso!

Puede crear un vínculo que lleve a las personas directamente a una interfaz de edición en el navegador. Tras bambalinas, suponiendo que el clicker está en GitHub pero no es suyo, esto creará un fork en su cuenta y le enviará un pull request. Cuando haga clic en el enlace de abajo, puede realmente hacer commit directamente al master de este repositorio.

¡HAGA CLIC AQUÍ para sugerir una edición a esta página!

Así es como el enlace aparece en código fuente de Markdown:

[¡HAGA CLIC AQUÍ para sugerir una edición a esta página!](https://github.com/STAT545-UBC/STAT545-UBC.github.io/edit/master/bit006_github-browsability-wins.md)

Y aquí está con los marcadores:

[INVITACIÓN A EDITAR](<URL to your repo>/edit/master/<path to your md file>)

Hasta donde se sabe, para hacer eso de una manera automática a través de un repositorio/sitio, necesitará usar Jekyll o algún otro sistema automatizado. Pero podría fácilmente hechar mano a tales enlaces en una escala pequeña.