From 11a02fad617428a48e11d0ace67ce38315f07f45 Mon Sep 17 00:00:00 2001
From: George Stagg <georgestagg@gmail.com>
Date: Sat, 27 Jul 2024 12:03:40 +0100
Subject: [PATCH] Docs: Grading with gradethis

---
 docs/_quarto.yml             |  1 -
 docs/exercises/gradethis.qmd | 86 +++++++++++++++++++++++++++++-------
 docs/exercises/python.qmd    | 46 -------------------
 3 files changed, 69 insertions(+), 64 deletions(-)
 delete mode 100644 docs/exercises/python.qmd

diff --git a/docs/_quarto.yml b/docs/_quarto.yml
index be3305a..2f5d73e 100644
--- a/docs/_quarto.yml
+++ b/docs/_quarto.yml
@@ -22,7 +22,6 @@ website:
           - exercises/environments.qmd
           - exercises/grading.qmd
           - exercises/gradethis.qmd
-          - exercises/python.qmd
       - section: Interactive Documents and Tutorials
         contents:
           - interactive/reactivity.qmd
diff --git a/docs/exercises/gradethis.qmd b/docs/exercises/gradethis.qmd
index 3cca0e3..676c3b9 100644
--- a/docs/exercises/gradethis.qmd
+++ b/docs/exercises/gradethis.qmd
@@ -1,42 +1,97 @@
 ---
-title: Grading R code using `gradethis`
+title: Grading with `{gradethis}`
+subtitble: Grade solutions to R exercises using the existing `{gradethis}` R package
 format: live-html
 webr:
   packages:
     - dplyr
+  render-df: head
 ---
 
 {{< include ../_extensions/live/_knitr.qmd >}}
 {{< include ../_extensions/live/_gradethis.qmd >}}
 
-Be sure to include the following to enable grading with `gradethis` in the `knitr` engine.
-In a future release, this will no longer be required.
+## Setup
 
+The `quarto-live` extension must be configured to use the `{gradethis}` R package in grading algorithms. Include the following lines after the document YAML header, but before your main content, in your Quarto document:
+
+````markdown
+{{{< include ./_extensions/live/_knitr.qmd >}}}
+{{{< include ./_extensions/live/_gradethis.qmd >}}}
+````
+
+::: {.callout-note}
+This configuration step is temporary. It is planned in a future version of `quarto-live` to be configurable by a key in the document YAML header instead.
+:::
+
+## Grading with a template solution
+
+First, create a `webr` exercise as normal,
+
+````{.markdown filename="gradethis.qmd"}
+```{{webr}}
+#| exercise: ex_1
+#| setup: true
+library(dplyr)
 ```
-{{{< include [...]/_extensions/live/_knitr.qmd >}}}
-{{{< include [...]/_extensions/live/_gradethis.qmd >}}}
+
+```{{webr}}
+#| caption: Sample Exercise
+#| exercise: ex_1
+starwars |> ______
 ```
+````
+
+Next, create a solution block for your exercise. Ensure that some template solution code is given in the form of a `webr` code block, linked to your exercise and with the cell option `solution: true` set.
+
+````{.markdown filename="gradethis.qmd"}
+::: {.solution exercise="ex_1"}
+
+#### Solution
+
+Use the `distinct()` function from the `{dplyr}` package.
+
+```{{webr}}
+#| exercise: ex_1
+#| solution: true
+starwars |> distinct(hair_color)
+```
+
+:::
+````
+
+Finally, create grading algorithm using `{gradethis}` package by adding a `webr` code block with the cell option `check: true` set. The grading algorithm should call `gradethis::grade_this_code()`.
+
+The template code provided in your solution block will be compared to the user provided code to automatically generate relevant feedback.
+
+````{.markdown filename="gradethis.qmd"}
+```{{webr}}
+#| exercise: ex_1
+#| check: true
+gradethis::grade_this_code()
+```
+````
+
+#### Output
 
 ```{webr}
-#| edit: false
-#| output: false
+#| exercise: ex_1
+#| setup: true
 library(dplyr)
 ```
 
-## Grading R code with `gradethis`
-
 ```{webr}
 #| caption: Sample Exercise
-#| exercise: example_1
+#| exercise: ex_1
 starwars |> ______
 ```
 
-::: {.solution exercise="example_1"}
+::: {.solution exercise="ex_1"}
 
 **Solution:**
 
 ```{webr}
-#| exercise: example_1
+#| exercise: ex_1
 #| solution: true
 starwars |> distinct(hair_color)
 ```
@@ -44,10 +99,7 @@ starwars |> distinct(hair_color)
 :::
 
 ```{webr}
-#| exercise: example_1
+#| exercise: ex_1
 #| check: true
-gradethis::grade_this_code(
-#  correct = "Correct!",
-#  incorrect = "Incorrect.",
-)
+gradethis::grade_this_code()
 ```
diff --git a/docs/exercises/python.qmd b/docs/exercises/python.qmd
deleted file mode 100644
index 31ff501..0000000
--- a/docs/exercises/python.qmd
+++ /dev/null
@@ -1,46 +0,0 @@
----
-title: Grading Python Solutions
-format: live-html
----
-
-```{ojs}
-//| output: false
-goal = Math.floor(Math.random() * 100);
-```
-
-Write a function to return the number ${goal}.
-
-```{pyodide}
-#| caption: Sample Exercise 1
-#| input:
-#|   - goal
-#| exercise: example_1
-def foo():
-    return 2
-```
-
-::: { .solution exercise="example_1" }
-
-**Fully worked solution:**
-
-```python
-def foo():            #<1>
-    return ${goal}    #<2>
-```
-1. Define the function `foo`, and then,
-2. Return the number ${goal}.
-
-:::
-
-```{pyodide}
-#| exercise: example_1
-#| check: true
-feedback = None
-if (not "foo" in locals() or not callable(foo)):
-    feedback = { "correct": False, "message": "I can't see your function!" }
-elif (foo() == goal):
-    feedback = { "correct": True, "message": "Nice work!" }
-else:
-    feedback = { "correct": False, "message": "Incorrect, sorry!" }
-feedback
-```