diff --git a/_episodes/05-rmarkdown-example.md b/_episodes/05-rmarkdown-example.md deleted file mode 100644 index 07cc3edb..00000000 --- a/_episodes/05-rmarkdown-example.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -source: Rmd -title: "Using RMarkdown" -teaching: 10 -exercises: 2 -questions: -- "How to write a lesson using RMarkdown?" -objectives: -- "Explain how to use RMarkdown with the new lesson template." -- "Demonstrate how to include pieces of code, figures, and challenges." -keypoints: -- "It shouldn't be difficult" ---- - -This episode demonstrates all the features that can be used when writing a -lesson in [RMarkdown][r-markdown]. - -To generate the site, you will need to have the following packages installed: - - -```r -install.packages(c("knitr", "stringr", "checkpoint")) -``` - -If the lesson uses additional packages, the script that converts the Rmd files -into markdown, will detect them and install them for you, when you run `make -serve` or `make site`. - -This first chunk is really important, and need to be included at the beginning of -each episode written in RMarkdown. - - -~~~ -source("../bin/chunk-options.R") -~~~ -{: .language-r} - -The rest of the lesson should be written as a normal RMarkdown file. You can -include chunk for codes, just like you'd normally do. - -Normal output: - - -~~~ -1 + 1 -~~~ -{: .language-r} - - - -~~~ -[1] 2 -~~~ -{: .output} - -Output with error message: - - -~~~ -x[10] -~~~ -{: .language-r} - - - -~~~ -[1] NA -~~~ -{: .output} - -Output generating figures: - - -~~~ -library(ggplot2) -ggplot(diamonds, aes(x = carat, y = price, color = cut)) + - geom_point() -~~~ -{: .language-r} - -plot of chunk plot-example - -For the challenges and their solutions, you need to pay attention to where the -`>` go and where to leave blank lines. You can include code chunks in both the -instructions and solutions. For instance this: - -``` -> ## Challenge: Can you do it? -> -> What is the output of this command? -> -> -> ~~~ -> paste("This", "new", "template", "looks", "good") -> ~~~ -> {: .language-r} -> -> > ## Solution -> > -> > -> > ~~~ -> > [1] "This new template looks good" -> > ~~~ -> > {: .output} -> {: .solution} -{: .challenge} -``` - -will generate this: - -> ## Challenge: Can you do it? -> -> What is the output of this command? -> -> -> ~~~ -> paste("This", "new", "template", "looks", "good") -> ~~~ -> {: .language-r} -> -> > ## Solution -> > -> > -> > ~~~ -> > [1] "This new template looks good" -> > ~~~ -> > {: .output} -> {: .solution} -{: .challenge} - -{% include links.md %} diff --git a/_episodes/01-design.md b/_episodes_rmd/01-design.Rmd similarity index 98% rename from _episodes/01-design.md rename to _episodes_rmd/01-design.Rmd index 7cc741a8..2780c0d0 100644 --- a/_episodes/01-design.md +++ b/_episodes_rmd/01-design.Rmd @@ -10,6 +10,9 @@ objectives: keypoints: - "Lessons are design in four stages: conceptual, summative, formative, and connective." --- +```{r, echo=FALSE} +source("../bin/chunk-options.R") +``` This episode describes how we go about designing lessons and why. For more information on how we design lessons and why, diff --git a/_episodes/02-tooling.md b/_episodes_rmd/02-tooling.Rmd similarity index 99% rename from _episodes/02-tooling.md rename to _episodes_rmd/02-tooling.Rmd index dc32bffc..528485de 100644 --- a/_episodes/02-tooling.md +++ b/_episodes_rmd/02-tooling.Rmd @@ -15,6 +15,9 @@ keypoints: - "Each page's configuration is stored at the top of that page." - "Groups of files are stored in collection directories whose names begin with an underscore." --- +```{r, echo=FALSE} +source("../bin/chunk-options.R") +``` This episode describes the tools we use to build and manage lessons. These simplify many tasks, but make other things more complicated. diff --git a/_episodes/03-organization.md b/_episodes_rmd/03-organization.Rmd similarity index 99% rename from _episodes/03-organization.md rename to _episodes_rmd/03-organization.Rmd index 74b8683f..d7e0aebc 100644 --- a/_episodes/03-organization.md +++ b/_episodes_rmd/03-organization.Rmd @@ -13,6 +13,9 @@ keypoints: - "The home page, reference guide, setup instructions, discussion page, and instructors' guide must be updated for each lesson." - "The Makefile stores commonly-used commands." --- +```{r, echo=FALSE} +source("../bin/chunk-options.R") +``` Each lesson is made up of *episodes*, which are focused on a particular topic and include time for both teaching and exercises. diff --git a/_episodes/04-formatting.md b/_episodes_rmd/04-formatting.Rmd similarity index 99% rename from _episodes/04-formatting.md rename to _episodes_rmd/04-formatting.Rmd index df266e9c..777312fa 100644 --- a/_episodes/04-formatting.md +++ b/_episodes_rmd/04-formatting.Rmd @@ -17,6 +17,9 @@ keypoints: - "Special sections are formatted as blockquotes that open with a level-2 header and close with a class identifier." - "Special sections may be callouts or challenges; other styles are used by the template itself." --- +```{r, echo=FALSE} +source("../bin/chunk-options.R") +``` A lesson consists of one or more episodes, each of which has: diff --git a/_episodes_rmd/05-bash-example.Rmd b/_episodes_rmd/05-bash-example.Rmd new file mode 100644 index 00000000..0caf1a35 --- /dev/null +++ b/_episodes_rmd/05-bash-example.Rmd @@ -0,0 +1,74 @@ +--- +source: Rmd +title: "Using Bash with RMarkdown" +teaching: 10 +exercises: 2 +questions: +- "How to call `bash` from RMarkdown?" +objectives: +- "Demonstrate how to include pieces of Bash code, figures, and challenges." +keypoints: +- "`bash` code blocks" +--- +```{r, echo=FALSE} +source("../bin/chunk-options.R") +``` + +This episode demonstrates all the features that can be used +when using Bash from [RMarkdown][r-markdown]. + +You can include chunk for codes, just like you'd normally do. + +Normal output: + +```{bash} +pwd +``` + +Output with error message: + +```{bash} +foo +``` + +For the challenges and their solutions, you need to pay attention to where the +`>` go and where to leave blank lines. You can include code chunks in both the +instructions and solutions. For instance + +``` +> ## Challenge: Can you do it? +> +> What is the output of this command? +> +> ```{bash, eval=FALSE}`r ''` +> ls data -a -F +> ``` +> +> > ## Solution +> > +> > ```{bash, echo=FALSE}`r ''` +> > ls data -a -F +> > ``` +> {: .solution} +{: .challenge} +``` + +will generate + +> ## Challenge: Can you do it? +> +> What is the output of this command? +> +> ```{bash, eval=FALSE} +> ls data -a -F +> ``` +> +> > ## Solution +> > +> > ```{bash, echo=FALSE} +> > ls data -a -F +> > ``` +> {: .solution} +{: .challenge} + +{% include links.md %} diff --git a/_episodes_rmd/06-python-example.Rmd b/_episodes_rmd/06-python-example.Rmd new file mode 100644 index 00000000..02fab150 --- /dev/null +++ b/_episodes_rmd/06-python-example.Rmd @@ -0,0 +1,83 @@ +--- +source: Rmd +title: "Using Python with RMarkdown" +teaching: 10 +exercises: 2 +questions: +- "How to call `python` from RMarkdown?" +objectives: +- "Demonstrate how to include pieces of Python code, figures, and challenges." +keypoints: +- "`python` code blocks" +--- +```{r, echo=FALSE} +source("../bin/chunk-options.R") +``` + +This episode demonstrates all the features that can be used +when using Python from [RMarkdown][r-markdown]. + +You can include chunk for codes, just like you'd normally do. + +Normal output: + +```{python} +1 + 1 +``` + +Output with error message: + +```{python} +x[10] +``` + +Output generating figures: + +```{python python-plot-example} +import matplotlib.pyplot as plt + +plt.plot([1, 2, 3, 4]) +plt.show() +``` + +For the challenges and their solutions, you need to pay attention to where the +`>` go and where to leave blank lines. You can include code chunks in both the +instructions and solutions. For instance + +``` +> ## Challenge: Can you do it? +> +> What is the output of this command? +> +> ```{python, eval=FALSE}`r ''` +> print("This new template looks good!") +> ``` +> +> > ## Solution +> > +> > ```{python, echo=FALSE}`r ''` +> > print("This new template looks good!") +> > ``` +> {: .solution} +{: .challenge} +``` + +will generate + +> ## Challenge: Can you do it? +> +> What is the output of this command? +> +> ```{python, eval=FALSE} +> print("This new template looks good!") +> ``` +> +> > ## Solution +> > +> > ```{python, echo=FALSE} +> > print("This new template looks good!") +> > ``` +> {: .solution} +{: .challenge} + +{% include links.md %} \ No newline at end of file diff --git a/_episodes_rmd/05-rmarkdown-example.Rmd b/_episodes_rmd/07-r-example.Rmd similarity index 95% rename from _episodes_rmd/05-rmarkdown-example.Rmd rename to _episodes_rmd/07-r-example.Rmd index b7aec20f..eb6787c4 100644 --- a/_episodes_rmd/05-rmarkdown-example.Rmd +++ b/_episodes_rmd/07-r-example.Rmd @@ -1,6 +1,6 @@ --- source: Rmd -title: "Using RMarkdown" +title: "Using R with RMarkdown" teaching: 10 exercises: 2 questions: @@ -50,7 +50,7 @@ x[10] Output generating figures: -```{r plot-example} +```{r r-plot-example} library(ggplot2) ggplot(diamonds, aes(x = carat, y = price, color = cut)) + geom_point() @@ -65,13 +65,13 @@ instructions and solutions. For instance this: > > What is the output of this command? > -> ```{r, eval=FALSE} +> ```{r, eval=FALSE}`r ''` > paste("This", "new", "template", "looks", "good") > ``` > > > ## Solution > > -> > ```{r, echo=FALSE} +> > ```{r, echo=FALSE}`r ''` > > paste("This", "new", "template", "looks", "good") > > ``` > {: .solution} diff --git a/_episodes/06-style-guide.md b/_episodes_rmd/08-style-guide.Rmd similarity index 99% rename from _episodes/06-style-guide.md rename to _episodes_rmd/08-style-guide.Rmd index 35a5c351..21e3ebd8 100644 --- a/_episodes/06-style-guide.md +++ b/_episodes_rmd/08-style-guide.Rmd @@ -9,6 +9,9 @@ objectives: keypoints: - "Keyboard keys need to use `` HTML tag." --- +```{r, echo=FALSE} +source("../bin/chunk-options.R") +``` ## Keyboard Key diff --git a/_episodes/07-checking.md b/_episodes_rmd/09-checking.Rmd similarity index 97% rename from _episodes/07-checking.md rename to _episodes_rmd/09-checking.Rmd index 2bfce050..264d104e 100644 --- a/_episodes/07-checking.md +++ b/_episodes_rmd/09-checking.Rmd @@ -13,6 +13,9 @@ keypoints: - "The checker uses the same Markdown parser as Jekyll." - "Lessons can be previewed by running `make serve`." --- +```{r, echo=FALSE} +source("../bin/chunk-options.R") +``` The lesson template comes with several utilities to simplify lesson development and maintenance. diff --git a/_episodes/08-coffee.md b/_episodes_rmd/10-coffee.Rmd similarity index 85% rename from _episodes/08-coffee.md rename to _episodes_rmd/10-coffee.Rmd index 3129b250..b309aad1 100644 --- a/_episodes/08-coffee.md +++ b/_episodes_rmd/10-coffee.Rmd @@ -3,6 +3,9 @@ layout: break title: "Coffee Break" break: 15 --- +```{r, echo=FALSE} +source("../bin/chunk-options.R") +``` Use the `break` layout for placeholder episodes representing coffee breaks and lunches. These episodes do *not* have exercises, questions, objectives, or keypoints in their metadata, diff --git a/setup.md b/setup.md index 57e12101..fe91c47c 100644 --- a/setup.md +++ b/setup.md @@ -9,13 +9,17 @@ changes made to it are easily mergable by downstream lessons. The `styles` repos bits that take Markdown files and render them as a lesson web page. For more information on how to develop lessons and maintain them, see our [lesson-example][lesson-example]. It will walk you through the basics of lesson design and how to use GitHub, Markdown and Jekyll for lesson development. Follow the instructions below to make -your own empty lesson in your own GitHub account. Once you've done that you can just write Markdown code and have +your own empty lesson in your own GitHub account. Once you've done that you can just write R Markdown code and have lesson web pages just like the [lesson-example][lesson-example] and all of our other lessons, but with your lesson content. Requirements: + * A GitHub account -* A working Python 3.4+ environment to run the lesson initialization script -* (Optional) A local install of [Jekyll](https://jekyllrb.com/) (version 3.2 or higher) which will require the Ruby language to be installed. +* A working Python (3.4 or higher) environment to run the lesson initialization script +* A working R (3.5 or higher) environment to convert the R Markdown files to Markdown files + * knitr (1.18 or higher) +* (Optional) A working Ruby environment to convert the Markdown files to HTML + * [Jekyll](https://jekyllrb.com/) (3.2 or higher) ## Creating a New Lesson