Auto-deploying documentation: Rtraining

In my last post on using GitHub, Travis-CI, and rmarkdown/knitr for automatically building and deploying documentation, I covered how I was able to do it with a containerised approach so things were faster. I also said my Rtraining repository was still too brittle to blog about. This has changed – WOO HOO!

The main thanks for that goes out to the new package ezknitr from Dean Attali. ezknitr takes the pain out of working directories, making my hierarchies much more resilient. I made a very simple reproduction of my scenarios in a repo called ezknitrTest – you can peruse it online or take a copy to play, but it essentially shows how you can use ezknitr::ezknit instead of rmarkdown::render and knitr::knit. It’s really handy!

So I went through and converted everything in my Rtraining to this and realised it messed up my slide decks – it’s been so long since I had built a pure knitr solution that I forgot that rmarkdown::render != knitr::knit. For my slidedecks, if I wanted the ioslides_presentation format, I needed to use rmarkdown::render. The problem with that has been the relative references to the CSS and the logo.

To solve this I read about the custom render formats capability and created a function that produces an ioslides_presentation but with my CSS preloaded by default. This now means that I can produce slides with better file referencing.

All in all, Rtraining is the culmination of my learnings over the past year of developing an analytical document pipeline that fits into my DataOps category. A summary of the features it uses are:

  • dynamic file identification
  • dynamic index page
  • custom render formats
  • custom CSS
  • ezknitr’d files
  • continuous integration
  • continuous deployment
  • containerised builds

It can now be browsed on stephlocke/github.io/Rtraining.

Posts in this series

  1. Automated documentation hosting on github via Travis-CI
  2. Auto-deploying documentation: multiple R vignettes
  3. Auto-deploying documentation: FASTER!
  4. Auto-deploying documentation: Rtraining
  5. Auto-deploying documentation: better change tracking of artefacts

PS If you’re looking to do a more book-like project, Hadley provides bookdown for your publication needs.

Search