Merge pull request datacarpentry#56 from fmichonneau/rmarkdown-tools

add tools to deal with episodes written in Rmd

Makefile

@@ -16,11 +16,11 @@ commands :
 	@grep -h -E '^##' ${MAKEFILES} | sed -e 's/## //g'
 
 ## serve          : run a local server.
-serve :
+serve : lesson-rmd
 	${JEKYLL} serve --config _config.yml,_config_dev.yml
 
 ## site           : build files but do not run a server.
-site :
+site : lesson-rmd
 	${JEKYLL} build --config _config.yml,_config_dev.yml
 
 ## figures        : re-generate inclusion displaying all figures.
@@ -35,6 +35,8 @@ clean :
 	@find . -name .DS_Store -exec rm {} \;
 	@find . -name '*~' -exec rm {} \;
 	@find . -name '*.pyc' -exec rm {} \;
+	@rm -rf ${RMD_DST}
+	@rm -rf fig/swc-rmd-*
 
 ## ----------------------------------------
 ## Commands specific to workshop websites.
@@ -48,7 +50,11 @@ workshop-check :
 ## ----------------------------------------
 ## Commands specific to lesson websites.
 
-.PHONY : lesson-check lesson-files lesson-fixme lesson-single
+.PHONY : lesson-check lesson-rmd lesson-files lesson-fixme lesson-single
+
+# RMarkdown files
+RMD_SRC = $(wildcard _episodes_rmd/??-*.Rmd)
+RMD_DST = $(patsubst _episodes_rmd/%.Rmd,_episodes/%.md,$(RMD_SRC))
 
 # Lesson source files in the order they appear in the navigation menu.
 SRC_FILES = \
@@ -70,6 +76,10 @@ HTML_FILES = \
   $(patsubst _extras/%.md,${DST}/%/index.html,$(wildcard _extras/*.md)) \
   ${DST}/license/index.html
 
+## lesson-rmd:    : convert Rmarkdown files to markdown
+lesson-rmd: $(RMD_SRC)
+	@bin/knit_lessons.sh
+
 ## lesson-check   : validate lesson Markdown.
 lesson-check :
 	@bin/lesson_check.py -s . -p ${PARSER}
@@ -79,6 +89,7 @@ unittest :
 
 ## lesson-files   : show expected names of generated files for debugging.
 lesson-files :
+	@echo 'RMarkdown:' ${RMD_SRC}
 	@echo 'source:' ${SRC_FILES}
 	@echo 'generated:' ${HTML_FILES}
 

bin/chunk-options.R

@@ -0,0 +1,42 @@
+# These settings control the behavior of all chunks in the novice R materials.
+# For example, to generate the lessons with all the output hidden, simply change
+# `results` from "markup" to "hide".
+# For more information on available chunk options, see
+# http://yihui.name/knitr/options#chunk_options
+
+library("knitr")
+
+fix_fig_path <- function(pth) file.path("..", pth)
+
+## We use the swc-rmd- prefix for the figures generated by the lssons
+## so they can be easily identified and deleted by `make clean`.  The
+## working directory when the lessons are generated is the root so the
+## figures need to be saved in fig/, but when the site is generated,
+## the episodes will be one level down. We fix the path using the
+## `fig.process` option.
+opts_chunk$set(tidy = FALSE, results = "markup", comment = NA,
+               fig.align = "center", fig.path = "fig/swc-rmd-",
+               fig.process = fix_fig_path)
+
+# The hooks below add html tags to the code chunks and their output so that they
+# are properly formatted when the site is built.
+hook_in <- function(x, options) {
+  stringr::str_c("\n\n~~~{.r}\n",
+                 paste0(x, collapse="\n"),
+                 "\n~~~\n{: .source}\n\n")
+}
+
+hook_out <- function(x, options) {
+  stringr::str_c("\n\n~~~\n",
+                   paste0(x, collapse="\n"),
+                 "\n~~~\n{: .output}\n\n")
+}
+
+hook_error <- function(x, options) {
+  stringr::str_c("\n\n~~~\n",
+                 paste0(x, collapse="\n"),
+                 "\n~~~\n{: .error}\n\n")
+}
+
+knit_hooks$set(source = hook_in, output = hook_out, warning = hook_error,
+               error = hook_error, message = hook_out)

bin/generate_md_episodes.R

@@ -0,0 +1,15 @@
+if (require("knitr")) {
+    if (packageVersion("knitr") < '1.9.19') {
+        stop("knitr must be version 1.9.20 or higher")
+    }
+} else stop("knitr 1.9.20 or above is needed to build the lessons.")
+
+if (!require("stringr"))
+    stop("The package stringr is required for generating the lessons.")
+
+src_rmd <- list.files(pattern = "??-*.Rmd$", path = "_episodes_rmd", full.names = TRUE)
+dest_md <- file.path("_episodes", gsub("Rmd$", "md", basename(src_rmd)))
+
+for (i in seq_along(src_rmd)) {
+    knitr::knit(src_rmd[i], output = dest_md[i])
+}

bin/knit_lessons.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+if [ -d "_episodes_rmd" ] ; then
+    Rscript -e "source('bin/generate_md_episodes.R')"
+fi