34  Hacer que un repositorio de GitHub sea navegable

La efectividad irrazonable de la navegabilidad de GitHub. Uno de mis 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 debas crear un sitio web adecuado para un proyecto. Quizás indefinidamente.

34.1 Sea inteligente con sus archivos

Mantenga los archivos en el formato más sencillo y compatible con sus objetivos principales. El texto sin formato es lo mejor. GitHub ofrece un manejo especial para ciertos tipos de archivos:

  • Archivos Markdown, que pueden estar destinados a la conversión, por ejemplo, a HTML.
  • Archivos Markdown denominados README.md
  • Archivos HTML, a menudo el resultado de compilar archivos Markdown.
  • Código fuente, como archivos .R
  • Archivos delimitados, como CSV y TSV
  • Archivos PNG

34.2 Supere sus complejos con respecto a: confirme productos derivados

Reconozcamos la incomodidad que algunas personas sienten al poner productos derivados bajo control de versiones. Específicamente, si tiene un documento R Markdown foo.Rmd, puede ser knit() para producir el producto intermedio foo.md, que se puede convertir al resultado final foo.html. ¿Cuál de esos archivos tiene “permitido” poner bajo control de versiones? Los partidarios de la línea dura de Source-is-real sólo dirán foo.Rmd, pero los pragmáticos saben que esto puede ser un serio fastidio en la vida real. Sólo porque puedo reconstruir todo desde cero, no significa que quiera hacerlo.

El tabú de mantener los productos derivados bajo control de versiones se origina en la compilación de ejecutables binarios desde el código fuente. El software creado en una Mac no funcionaría en Windows, por lo que tenía sentido mantener estos binarios fuera del sagrado repositorio de código fuente. Además, se podría asumir que las personas con acceso al repositorio tienen la pila de desarrollo completa y disfrutan de las oportunidades de utilizarla. 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, mirar las diferencias de foo.md o foo-figure-01.png puede resultar extremadamente informativo. Esto también es cierto en proyectos de análisis de datos más grandes después de una operación de limpieza; realizar todas las operaciones. Al observar las diferencias en los productos posteriores, a menudo se detectan cambios inesperados. Esto puede alertarle sobre 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 terminan en su repositorio. No te preguntaré cómo llegaron allí.

34.3 Markdown

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

Explota esto agresivamente. Haga de Markdown su formato predeterminado para archivos de texto narrativo y utilícelos libremente para insertar notas para usted y para otras personas en un repositorio alojado en Github. Es una manera fácil de obtener pseudopáginas web dentro de un proyecto “gratis”. Es posible que ni siquiera compiles estos archivos en HTML explícitamente; En muchos casos, la vista previa HTML que ofrece GitHub es todo lo que necesitas.

34.4 R Markdown

¿Qué significa esto para los archivos R Markdown? Mantener Markdown intermedio. O solo renderizar en Markdown. Confirme tanto foo.Rmd como foo.md, incluso si elige .gitignore el producto final, p.e. foo.html o foo.pdf o foo.docx. Desde septiembre de 2014, GitHub representa muy bien los archivos R Markdown, como Markdown, y con resaltado de sintaxis adecuado, lo cual es genial. Pero, por supuesto, los bloques de código simplemente permanecen ahí sin ejecutarse, por lo que mi consejo sobre mantener Markdown sigue siendo válido.

Si su formato de salida de destino no es Markdown, desea YAML frontmatter eso se parece a esto para .Rmd:

---
title: "Something fascinating"
author: "Jenny Bryan"
date: "`r format(Sys.Date())`"
output:
  html_document:
    keep_md: TRUE
---

o así para .R:

#' ---
#' title: "Something fascinating"
#' author: "Jenny Bryan"
#' date: "`r format(Sys.Date())`"
#' output:
#'   html_document:
#'     keep_md: TRUE
#' ---

La parte keep_md: TRUE dice que se mantenga el Markdown intermedio. En RStudio, al editar .Rmd, haga clic en el engranaje junto a “Knit HTML” para obtener ayuda sobre la creación de YAML.

Desde 2016, rmarkdown ofrece un formato de salida personalizado para Markdown con sabor a GitHub, github_document. Lea acerca de flujos de trabajo de R Markdown para ejemplos explícitos de cómo utilizar esto. Si Markdown es su formato de salida de destino, su YAML puede ser aún más simple y verse así por .Rmd:

---
output: github_document
---

o así para .R:

#' ---
#' output: github_document
#' ---

Para obtener un documento rápido e independiente que no encaje perfectamente en un repositorio o proyecto (todavía), conviértalo en Gist. Ejemplo: consejos de Hadley Wickham sobre lo que debe hacer para convertirse en científico de datos. Los gists pueden contener varios archivos, por lo que aún puedes proporcionar el script R o la fuente R Markdown y el Markdown resultante, como lo hice en este artículo de Consejos para tabulación cruzada obtenidos en Twitter. He recopilado ejemplos YAML para todos los escenarios anteriores en esencia.

34.5 README.md

Probablemente ya sepas que GitHub muestra README.md en el nivel superior de tu repositorio como la página de inicio de facto. Esto es análogo a lo que sucede cuando apunta un navegador web a un directorio en lugar de a 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 desempeñan exactamente esta función 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. Y luego cree un archivo README.md para anotar estos archivos, recopilar enlaces relevantes, etc. Ahora, cuando navegue al subdirectorio en GitHub, simplemente aparecerá el README.md muy bien renderizado. El repositorio de GitHub que respalda el gapminder data package has a README en el subdirectorio data-raw eso explica exactamente cómo se crean los datos del paquete. De hecho, se genera programáticamente a partir de README.Rmd.

Algunos repositorios constan únicamente de README.md. Ejemplos: artículos de Jeff Leek sobre Cómo compartir datos con un estadístico o Desarrollar paquetes de R. Me estoy volviendo cada vez más fanático de los repositorios solo README que de los gists porque los problemas con los repositorios activan notificaciones, mientras que los comentarios sobre gists no.

Si tiene un directorio lleno de figuras compatibles con la web, como PNG, puede usar código como este generar un README.md para una rápida galería de bricolaje, como lo ha hecho Karl Broman con sus FruitSnacks. Hice lo mismo con todas las fantásticas portadas de libros de O RLY hecho por The Practical Dev.

También he usado este dispositivo para compartir diapositivas de Keynote en GitHub (¡mea culpa!). Exportarlos como imágenes PNG y colocarlos en una galería README: diapositivas en organización de archivos and some en denominación de archivos.

34.6 Encontrar cosas

Vale, estos son consejos puros de GitHub, pero si has llegado hasta aquí, obviamente estás más interesado.

  • Presione t para activar el buscador de archivos siempre que esté en la vista de archivos y directorios de un repositorio. IMPRESIONANTE, especialmente cuando hay archivos escondidos en muchos subdirectorios.
  • Presione y para obtener un enlace permanente cuando estás viendo un archivo específico. Observe los cambios en la URL. Esto es importante si está a punto de vincular a un archivo o a líneas específicas. De lo contrario, tus enlaces se romperán fácilmente en el futuro. Si el archivo se elimina o se le cambia el nombre, o si se insertan o eliminan líneas, sus enlaces ya no apuntarán a lo que pretendía. Utilice y para obtener enlaces que incluyan una confirmación específica en la URL.

34.7 HTML

Si tiene un archivo HTML en un repositorio de GitHub, simplemente visitar el archivo muestra el HTML sin formato. Aquí hay un bonito y feo ejemplo:

Nadie quiere mirar eso. Puede proporcionar esta URL a rawgit.com para publicar este HTML de forma más adecuada y obtener una vista previa decente..

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

2018-10-09 actualización: RawGit announced que se encuentra en una fase de puesta de sol y pronto cerrará. Ellos recomendaron: jsDelivr, GitHub Pages, CodeSandbox, y unpkg como alternativas.

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

Quizás también quieras consultar esta extensión de Chrome o Vista previa HTML de GitHub y BitBucket, aunque recientemente he tenido más éxito con rawgit.com. (Ninguno de los dos funciona con repositorios privados de GitHub, lo cual es una razón más para conservar archivos de rebajas intermedios para HTML, como se describe anteriormente.)

A veces, incluir archivos HTML hará que GitHub piense que su repositorio R es HTML. Además de ser un poco molesto, esto puede dificultar que las personas encuentren su trabajo si buscan específicamente repositorios de R. Puedes excluir estos archivos o directorios de las estadísticas de idioma de GitHub agregando un archivo .gitattributes eso los marca como “documentación” en lugar de código. Ver un ejemplo aquí.

34.8 Código fuente

Notarás que GitHub resalta automáticamente la sintaxis del código fuente. Por ejemplo, observe el color de este script R. La extensión del archivo es el principal determinante de si y cómo se aplicará el resaltado de 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 esta sea otra razón para seguir las convenciones en el uso de extensiones de archivos.

Tenga en cuenta que también puede hacer clic en “Sin formato” en este contexto para obtener solo el texto sin formato y nada más que el texto sin formato.

34.9 Archivos delimitados

GitHub representará muy bien datos tabulares en forma de archivos .csv (separados por comas) y .tsv (separados por tabulación). Puedes leer más en la publicación del blog anunciando esta característica en agosto de 2013 o en esta página de ayuda de GitHub.

Consejo: ¡aprovecha esto! Si algo en su repositorio se puede almacenar de forma natural como datos delimitados, hágalo por todos los medios. Haga de la coma o la tabulación su delimitador predeterminado y use los sufijos de archivo que GitHub espera. He notado que GitHub se confunde más fácilmente que R en cosas como las citas, así que siempre inspeccione el archivo .csv o .tsv renderizado por GitHub en el navegador. Es posible que tengas que realizar una limpieza ligera para que el renderizado automático funcione correctamente. Piense en ello como otra forma más de conocer las imperfecciones de sus datos.

Aquí hay un ejemplo de un archivo delimitado por tabulaciones en GitHub: lotr_clean.tsv, encontrado originalmente aquí (no, IBM cerró manyeyes en julio de 2015).

Tenga en cuenta que también puede hacer clic en “Sin formato” en este contexto para obtener solo el texto sin formato y nada más que el texto sin formato.

34.10 PNGs

PNG es el formato “obvio” para almacenar cifras para la web. Pero a muchos de nosotros nos gusta un formato basado en vectores, como PDF, para figuras de uso general. En pocas palabras: los archivos PNG te volverán menos loco que los archivos PDF en GitHub. Para reducir la molestia de ver figuras en el navegador, asegúrese de tener una versión PNG en el repositorio.

Ejemplos:

  • Esta figura PNG simplemente aparece en el navegador
  • Una cifra diferente almacenada como PDF produce el temido y molesto aumento de velocidad “Ver Raw”. Tendrás que hacer clic y, en mi navegador OS +, esperar a que el PDF aparezca en un visor de PDF externo. 2015-06-19 update: Desde que escribí esto por primera vez, GitHub ha [elevado su tratamiento de archivos PDF] (https://github.com/blog/1974-pdf-viewing), así que YAY. Es lento pero funciona.

Esperemos que estemos avanzando hacia un mundo en el que se pueda tener “web amigable” y “vectorial” al mismo tiempo, sin dolores de cabeza innecesarios. A partir de octubre de 2014, GitHub proporciona visualización y diferenciación mejoradas de SVG. Así que no leas este consejo como algo que desalienta a los SVG. ¡Hazlos! Pero considere mantener un PNG como respaldo de emergencia por ahora.

34.11 Otros formatos de documentos

Es posible que también tenga un documento que desea que otros puedan explorar e interactuar, pero no está en formato Markdown. Afortunadamente, el programa Pandoc de código abierto, escrito por John MacFarlane, le permite convertir una variedad de formatos a Markdown, incluido el formato ampliamente utilizado .docx.

Cuando hace clic en el botón Knit en RStudio, en realidad es Pandoc el que realiza la conversión final a formatos HTML o Microsoft Word (.docx). Si está dispuesto a utilizar la línea de comandos, puede realizar la conversión opuesta (por ejemplo, .docx a .md), normalmente conservando características como encabezados, tablas, ecuaciones e incluso figuras.

Como algunos repetitivos, ejecutándose en Windows PowerShell pandoc --extract-media .\media -f docx .\example.docx -t markdown_github -o example_image.md convierte un documento de Word llamado example.docx para marcar y extrae las imágenes en un directorio que corresponde a una ruta de archivo en el documento example.md recién creado. Una lista completa de formatos admitidos y códigos de ejemplo para conversiones están disponibles en https://pandoc.org/.

También puede realizar conversiones simples a rebajas con sabor a GitHub desde diferentes tipos de rebajas (Pandoc admite markdown_mmd, markdown_php_extra y markdown_strict) desde dentro de RStudio. Para hacerlo, debe cambiar el nombre del archivo cambiando la extensión (por ejemplo, de foo.md a foo.Rmd), luego abra el archivo renombrado en RStudio y agregue el siguiente texto en la parte superior del documento.

---
output: github_document
---

Luego puede hacer clic en “Knit” y luego en “Knit to github document” para realizar la conversión. Consulte Formato de salida para obtener más detalles sobre cómo controlar los formatos de salida con el frontmatter YAML.

34.12 Vincular a un archivo ZIP de su repositorio

La navegabilidad de GitHub hace que su trabajo sea accesible para las personas que se preocupan por su contenido pero que (todavía) no usan Git. ¿Qué pasa si esa persona quiere todos los archivos? Sí, GitHub ofrece un botón “Descargar ZIP” en el que se puede hacer clic. Pero, ¿qué sucede si desea incluir un enlace en un correo electrónico u otro documento? Si agrega /archive/master.zip al final de la URL de su repositorio, creará 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

¡Ve a buscar en tu carpeta de descargas!

34.13 Enlaces y figuras incrustadas.

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

  • La misma idea también funciona para las imágenes. ![](image.png) incluirá image.png ubicado en el directorio actual

34.14 Deja que la gente te corrija en Internet

¡Les encanta eso!

Puede crear un enlace que lleve a las personas directamente a una interfaz de edición en el navegador. Detrás de escena, suponiendo que la persona que hizo clic haya iniciado sesión en GitHub pero no sea usted, esto creará una bifurcación en su cuenta y le enviará una solicitud de cambio. Cuando hago clic en el enlace a continuación, puedo enviarme directamente al master para este repositorio.

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

Así es como se ve ese enlace en la fuente de Markdown:

[¡HAGA CLIC AQUÍ para sugerir una edición de esta página!](https://github.com/jennybc/happy-git-with-r/edit/master/workflows-make-github-repo-browsable.Rmd)

y aquí está con marcadores de posición:

[INVITACIÓN A EDITAR](<URL to your repo>/edit/master/<ruta al archivo fuente de destino>)

Hasta donde se, para hacer eso de una manera hábil y automática en todo un repositorio/sitio, debe usar Jekyll o algún otro sistema automatizado. Pero podrías codificar fácilmente dichos enlaces a pequeña escala.