Automatic website for the Geocomputation with R solutions

New solutions website

Firstly, let’s take a look at the bigger picture. Exercises are shown at the end of the book chapters, for example, exercises for chapter 6 can be seen at https://geocompr.robinlovelace.net/raster-vector.html#exercises-4. You may notice that this exercises section starts with a description of prerequisites, and then several questions are listed. However, what to do when I want to find solutions to these problems or compare my results with those provided by the book authors? Then, we can visit the corresponding chapter in the solution website at https://geocompr.github.io/solutions/raster-vector.html. Note that the solution website contains the same content as the exercises section, and extends it with the solution code, code results, and newly created figures.

Solutions

Next, let’s dive deeper to see how it works. We can look at the source code of the solution website first – https://github.com/geocompr/solutions, and solutions for chapter 6 are at https://github.com/geocompr/solutions/blob/main/06-raster-vector.Rmd. If you open the last link, you should see a code looking like that:

```{r setup, echo=FALSE, results='hide'}`r ''`
ex = tempfile(fileext = ".Rmd")
on.exit(unlink(ex))
download.file("https://raw.githubusercontent.com/Robinlovelace/geocompr/main/_06-ex.Rmd", ex)
```

```{r, echo=FALSE, results='asis'}`r ''`
res = knitr::knit_child(ex, quiet = TRUE, options = list(include = TRUE))
cat(res, sep = '\n')
```

What is going on here? In short, we have two code chunks. The first (hidden) code chunk downloads a _06-ex.Rmd file from the Robinlovelace/geocompr repository. Ok, but how does this _06-ex.Rmd document looks like? You can see its content at https://raw.githubusercontent.com/Robinlovelace/geocompr/main/_06-ex.Rmd. It is a mix of text (mainly exercises questions) and R code chunks. Note here that most code chunks do not have any code chunks options set, except the first one. We wanted the first code chunk to be visible on the main book and the solution websites, so we used include = TRUE.

The second code chunk takes the downloaded document and knits it with a new global option, include = TRUE. This option make sure that we will show all possible outputs from _06-ex.Rmd, including numerical results and plots.

Exercises

The above section explained how we could see exercises and solutions on the solution website. However, how is it possible that we can only see the exercise text in the book? Let’s look at the bottom of the source code of the 6th chapter at https://github.com/Robinlovelace/geocompr/blob/main/06-raster-vector.Rmd:

## Exercises

```{r, echo=FALSE, results='asis'}`r ''`
res = knitr::knit_child('_06-ex.Rmd', quiet = TRUE, options = list(include = FALSE, eval = FALSE))
cat(res, sep = '\n')
```

There is only one short code chunk – it knits the same document, _06-ex.Rmd, however using different global options, include = FALSE, eval = FALSE. This assures that the book’s readers would not see any solutions’ code chunks or their outputs.

Workflow

Now we know all of the pieces of the puzzle. The last step is to connect them together with GitHub Actions.

Our workflow is as follows:

1. We add/update/modify exercises and their solutions stored in a file per chapter, e.g., _06-ex.Rmd
2. We push the changes to the main book repository on GitHub (Robinlovelace/geocompr)
3. The book is automatically built using a GitHub Actions workflow, including exercises (but not solutions!)
4. Once a week, another GitHub Actions workflow runs in the solutions repository.

This approach ensures that the solutions are always up-to-date, reproducible, and in sync. with the manuscript. It creates a resources dedicated to the exercises and their solutions, helping people learn. It should also encourage others to get involved: can you think of another exercise or an alternative solution to existing exercises? You have all the info you need to contribute now. Let us know your comments or suggestions at https://github.com/geocompr/solutions! Pull Requests are also welcome!