bookdown: Escritura de libros y documentos técnicos con R Markdown

6.2 GitHub

Puede alojar su libro en GitHub de forma gratuita a través de GitHub Pages (https://pages.github.com). GitHub sopporta Jekyll (http://jekyllrb.com), un constructor de sitios web estático, para construir un sitio web a partir de archivos Markdown. Ese puede ser el caso de uso más común de GitHub pages, pero GitHub también es compatible con archivos HTML estáticos arbitrarios, por ende puede albergar los archivos de salida HTML de su libro en GitHub. La clave es crear un archivo oculto .nojekyll que le indique a GitHub que su sitio web no se construirá a través de Jekyll, ya que el resultado HTML de bookdown ya es un sitio web independiente.

# se asume que ha inicializado el repositorio de git,
# y en este momento se encuentra en el directorio del repositorio del libro

# crear un archivo oculto .nojekyll
touch .nojekyll
# agregar a git aquí porque no se mostrará en RStudio
git add .nojekyll

Si está en Windows, es posible que no tenga el comando touch, puede crear el archivo en R usando `file.create(‘.nojekyll’).

Un enfoque es publicar su libro como un sitio en GitHub Pages desde una carpeta /docs en su rama principal master como se describe en GitHub Help.. Primero, configure el directorio de salida de su libro para que sea /docs agregando la línea output_dir: "docs" al archivo de configuración _bookdown.yml. Luego, después de enviar sus cambios a GitHub, vaya a la configuración de su repositorio y en “GitHub Pages” cambie el “Source” para que sea “master branch /docs folder”. En este caso, el archivo .nojekyll tiene que estar en la carpeta /docs.

Un enfoque alternativo es crear una rama gh-pages en su repositorio, construir el libro, poner la salida HTML (incluyendo todos los recursos externos, como imágenes, CSS y archivos JavaScript) en esta rama, y empujar la rama al repositorio remoto. Si el repositorio de libro no tiene la rama gh-pages, puede utilizar los siguientes comandos para crear una:

# se asume que ha inicializado el repositorio git,
# y en este momento se encuentra en el directorio del repositorio del libro

# crear una rama llamada gh-pages y limpiar todo
git checkout --orphan gh-pages
git rm -rf .

# crear un archivo aoculto .nojekyll
touch .nojekyll
git add .nojekyll

git commit -m"Initial commit"
git push origin gh-pages

Después de haber configurado GIT, el resto del trabajo puede ser automatizado a través de una secuencia de comandos (Shell, R o Makefile, dependiendo de su preferencia). Básicamente, se compila el libro a HTML, a continuación, ejecuta los comandos git para empujar los archivos en GitHub, pero es probable que no quiera hacer esto una y otra vez de forma manual y localmente. Puede ser muy útil para automatizar el proceso de publicación por completo en la nube, por lo que una vez que se haya configurado correctamente, todo lo que tiene que hacer ahora es escribir el libro y empujar los archivos de origen Rmd a GitHub, y su libro siempre será construido de forma automática y publicado hacia el servidor.

Un servicio que se puede utilizar es Travis CI (https://travis-ci.org). . Es libre para repositorios públicos en GitHub, y fue diseñado para la integración continua (CI) de los paquetes de software. Travis CI se puede conectar a GitHub en el sentido de que cada vez que se empuja a GitHub, Travis puede ser activado para ejecutar ciertos comandos/scripts en la versión más reciente de su repositorio.¹² Estos comandos se especifican en un archivo YAML llamado .travis.yml en el directorio raíz de su repositorio, y están por lo general con el propósito de pruebas de software, pero en realidad son bastante abiertos, lo que significa que puede ejecutar arbitrariamente programas en una máquina Travis (virtual). Esto significa que sin duda puede ejecutar sus propios scripts para construir su libro sobre Travis. Nota: Travis sólo es compatible con Ubuntu y Mac OS X en este momento, por lo que debe tener algunos conocimientos básicos acerca de los comandos de Linux/Unix.

La siguiente pregunta es, cómo publicar el libro construido sobre Travis a GitHub? Básicamente tiene que conceder acceso de escritura a Travis a su repositorio GitHub. Esta autorización se puede hacer a través de varias maneras, y la más fácil a los principiantes puede ser una señal de acceso personal. A continuación se presentan algunos pasos que puede seguir:

Crear un token de acceso personal para su cuenta en GitHub (asegúrese de que sea posible el funcionamiento “repo”, por lo que el uso de esta muestra permitirá escrito a sus repositorios de GitHub);
Cifrarlo en la variable de entorno GITHUB_PAT a través de la línea de comandos travis encrypt y almacenarlo en .travis.yml, por ejemplo travis encrypt GITHUB_PAT=TOKEN. Si usted no sabe cómo instalar o utilizar la herramienta de línea de comandos Travis, simplemente guarde esta variable de entorno a través de https://travis-ci.org/user/repo/settings donde user es su ID de GitHub, y repo es el nombre del repositorio;
Puede clonar esta rama gh-pages en Travis utilizando el token de GitHub, añadir los archivos HTML de salida de R Markdown (no se olvide de añadir figuras y archivos de estilo CSS, también), y empujar al repositorio remoto.

Suponga que usted está en la rama master en este momento (donde pone los archivos de origen Rmd), y ha compilado el libro en el directorio _book. Lo que puede hacer al lado de Travis es:

# configure su nombre y email si no lo ha hecho anteriormente
git config --global user.email "you@example.com"
git config --global user.name "Your Name"

# clone el repository al directorio de salida del libro
git clone -b gh-pages \
  https://${GITHUB_PAT}@github.com/${TRAVIS_REPO_SLUG}.git \
  book-output
cd book-output
git rm -rf *
cp -r ../_book/* ./
git add --all *
git commit -m"Update the book"
git push origin gh-pages

El nombre de la variable GITHUB_PAT y el nombre del directorio book-output son arbitrarios, y se puede usar cualquier nombre que desee, siempre y cuando los nombres no entren en conflicto con los nombres de variables de entorno existentes o nombres de directorio. Esta secuencia de comandos, junto con la escritura de la estructura mencionamos en la sección ??, se puede poner en la rama master como scripts de shell, por ejemplo, puede nombrarlos a ellos como _build.sh y _deploy.sh. Luego, su .travis.yml puede tener este aspecto:

language: r

env:
  global:
    - secure: A_LONG_ENCRYPTED_STRING

before_script:
  - chmod +x ./_build.sh
  - chmod +x ./_deploy.sh

script:
  - ./_build.sh
  - ./_deploy.sh

La clave language le dice a Travis que utilice una máquina virtual que ha instalado R. La clave secure es el token de acceso personal encriptada. Si ya ha guardado la variable GITHUB_PAT utilizando la interfaz Web Travis en lugar de la herramienta de línea de comandos travis encrypt, puede dejar de lado esta clave.

Como este servicio Travis es principalmente para el control de paquetes en R, también se necesita un (falso) archivo de DESCRIPTION como si el repositorio de libro fuera un paquete R. La única cosa en este archivo que realmente importa es la especificación de las dependencias. Todas las dependencias se instalarán a través deL paquete devtools. Si una dependencia está en CRAN o BioConductor, sólo tiene que incluirla en el campo Imports del archivo DESCRIPTION. Si está en GitHub, puede utilizar el campo Remotes para listar el nombre de su repositorio. A continuación se muestra un ejemplo:

Package: placeholder
Title: Does not matter.
Version: 0.0.1
Imports: bookdown, ggplot2
Remotes: rstudio/bookdown

Si se utiliza la infraestructura basada en contenedores de Travis, puede habilitar el almacenamiento en caché mediante el uso de sudo:false en .travis.yml. Normalmente debería almacenar en caché al menos dos tipos de directorios: el directorio de la figura (por ejemplo, _main_files) y el directorio de caché (por ejemplo,_main_cache). Estos nombres de los directorios también pueden ser diferentes si se ha especificado las opciones del chunk knitr ``fig.path y cache.path, pero se recomienda encarecidamente que no cambie estas opciones. Los directorios de las figuras y de caché se almacenan en el directorio _bookdown_files del directorio raíz del libro. Un archivo .travis.yml que ha permitido el almacenamiento en caché de la figura knitr los y directorios de caché pueden tener configuraciones adicionales`sudo y cache como este:

sudo: false

cache:
  packages: yes
  directories:
    - $TRAVIS_BUILD_DIR/_bookdown_files

Si el libro consume mucho tiempo para construir, puede utilizar las configuraciones anteriores de Travis para ahorrar tiempo. Note que packages: yes significa que los paquetes instalados en R Travis también están almacenados en caché.

Todas las secuencias de comandos y configuraciones anteriores se pueden encontrar en el repositorio bookdown-demo: https://github.com/rstudio/bookdown-demo/. Si los copia a su propio repositorio, por favor recuerde que debe cambiar la tecla secure en .travis.yml usando su propia variable de cifrado GITHUB_PAT.

GitHub y Travis CI ciertamente no son las únicas opciones para construir y publicar su libro. Usted es libre para almacenar y publicar el libro en su propio servidor.

Debe autorizar el servicio Travis CI para su repositorio en GitHub primero . Ver https://docs.travis-ci.com/user/getting-started/ de cómo empezar con Travis CI.↩