Skip to content

Commit 7704c50

Browse files
Yanay1Yanay1
authored
Merge pull request #20 from data-8/documentation-updates
Update documentation and add Gofer demo files
2 parents c6bfcc8 + a27c193 commit 7704c50

6 files changed

Lines changed: 254 additions & 3 deletions

File tree

‎docs/demo/Dockerfile‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
FROM jupyter/minimal-notebook
2+
3+
EXPOSE 8888
4+
5+
COPY Gofer_Demo.ipynb .
6+
7+
COPY tests tests
8+
9+
RUN pip install gofer-grader
10+
11+
CMD ["jupyter", "notebook"]

‎docs/demo/Gofer_Demo.ipynb‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "code",
5+
"execution_count": null,
6+
"metadata": {},
7+
"outputs": [],
8+
"source": [
9+
"from gofer.ok import check"
10+
]
11+
},
12+
{
13+
"cell_type": "markdown",
14+
"metadata": {},
15+
"source": [
16+
"# Gofer Grader Demo\n",
17+
" \n",
18+
"Gofer uses the ok test format to autograde notebook solutions. Below is the test file for this notebook, located in `tests/demo.ok`. In short, the test file contains python code to test the value of certain variables. More details are in the documentation, in `ok-test-format.ok`."
19+
]
20+
},
21+
{
22+
"cell_type": "markdown",
23+
"metadata": {},
24+
"source": [
25+
"```\n",
26+
"test = {\n",
27+
" 'name': 'Gofer Grader Demo',\n",
28+
" 'suites': [\n",
29+
" {\n",
30+
" 'cases': [\n",
31+
" {\n",
32+
" 'code': r\"\"\"\n",
33+
" >>> # It looks like you didn't give anything the name\n",
34+
" >>> # seconds_in_a_decade. Maybe there's a typo?\n",
35+
" >>> 'seconds_in_a_decade' in vars()\n",
36+
" True\n",
37+
" \"\"\"\n",
38+
" },\n",
39+
" {\n",
40+
" 'code': r\"\"\"\n",
41+
" >>> # The number of seconds you computed is too low by at least\n",
42+
" >>> # a factor of 5.\n",
43+
" >>> # There are 10 years, some number of days in a year, some\n",
44+
" >>> # number of hours per day, minutes per hour, and seconds\n",
45+
" >>> # per minute. For example, this is almost right:\n",
46+
" >>> # seconds_in_a_decade = 10*365*24*60*60\n",
47+
" >>> seconds_in_a_decade > 60000000\n",
48+
" True\n",
49+
" \"\"\"\n",
50+
" },\n",
51+
" {\n",
52+
" 'code': r\"\"\"\n",
53+
" >>> # You're close! Perhaps you didn't account for leap years correctly.\n",
54+
" >>> # There were 2 leap years and 8 non-leap years in this period.\n",
55+
" >>> # Leap years have 366 days instead of 365.\n",
56+
" >>> 315360000 < seconds_in_a_decade < 331344000\n",
57+
" True\n",
58+
" \"\"\"\n",
59+
" },\n",
60+
" {\n",
61+
" 'code': r\"\"\"\n",
62+
" >>> seconds_in_a_decade == 315532800\n",
63+
" True\n",
64+
" \"\"\"\n",
65+
" }\n",
66+
" ]\n",
67+
" }\n",
68+
" ]\n",
69+
"}\n",
70+
"```"
71+
]
72+
},
73+
{
74+
"cell_type": "markdown",
75+
"metadata": {},
76+
"source": [
77+
"Here's a sample question, with a corresponding check.\n",
78+
" \n",
79+
"Compute the number of seconds in a decade."
80+
]
81+
},
82+
{
83+
"cell_type": "code",
84+
"execution_count": null,
85+
"metadata": {},
86+
"outputs": [],
87+
"source": [
88+
"seconds_in_a_decade = 1"
89+
]
90+
},
91+
{
92+
"cell_type": "markdown",
93+
"metadata": {},
94+
"source": [
95+
"Below is an example of what happens when tests fail. Observe that the comments are printed as well, to give the students feedback on their error."
96+
]
97+
},
98+
{
99+
"cell_type": "code",
100+
"execution_count": null,
101+
"metadata": {
102+
"scrolled": true
103+
},
104+
"outputs": [],
105+
"source": [
106+
"check('tests/demo.ok')"
107+
]
108+
},
109+
{
110+
"cell_type": "markdown",
111+
"metadata": {},
112+
"source": [
113+
"Now let's set the correct answer."
114+
]
115+
},
116+
{
117+
"cell_type": "code",
118+
"execution_count": null,
119+
"metadata": {},
120+
"outputs": [],
121+
"source": [
122+
"seconds_in_a_decade = (365*8 + 366*2) * 24 * 60 * 60"
123+
]
124+
},
125+
{
126+
"cell_type": "markdown",
127+
"metadata": {},
128+
"source": [
129+
"Here is an example of a successful test."
130+
]
131+
},
132+
{
133+
"cell_type": "code",
134+
"execution_count": null,
135+
"metadata": {},
136+
"outputs": [],
137+
"source": [
138+
"check('tests/demo.ok')"
139+
]
140+
},
141+
{
142+
"cell_type": "markdown",
143+
"metadata": {},
144+
"source": [
145+
"Feel free to edit `demo.ok` file and add more tests. You can find it in the `tests/` folder in the Jupyter directory. "
146+
]
147+
}
148+
],
149+
"metadata": {
150+
"kernelspec": {
151+
"display_name": "Python 3",
152+
"language": "python",
153+
"name": "python3"
154+
},
155+
"language_info": {
156+
"codemirror_mode": {
157+
"name": "ipython",
158+
"version": 3
159+
},
160+
"file_extension": ".py",
161+
"mimetype": "text/x-python",
162+
"name": "python",
163+
"nbconvert_exporter": "python",
164+
"pygments_lexer": "ipython3",
165+
"version": "3.7.1"
166+
}
167+
},
168+
"nbformat": 4,
169+
"nbformat_minor": 2
170+
}

‎docs/demo/tests/demo.ok‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
test = {
2+
'name': 'Gofer Grader Demo',
3+
'suites': [
4+
{
5+
'cases': [
6+
{
7+
'code': r"""
8+
>>> # This is a sample test. Note the comments
9+
>>> # to give students feedback, followed by a general test.
10+
>>> True
11+
True
12+
"""
13+
},
14+
{
15+
'code': r"""
16+
>>> # It looks like you didn't give anything the name
17+
>>> # seconds_in_a_decade. Maybe there's a typo?
18+
>>> 'seconds_in_a_decade' in vars()
19+
True
20+
"""
21+
},
22+
{
23+
'code': r"""
24+
>>> # The number of seconds you computed is too low by at least
25+
>>> # a factor of 5.
26+
>>> # There are 10 years, some number of days in a year, some
27+
>>> # number of hours per day, minutes per hour, and seconds
28+
>>> # per minute. For example, this is almost right:
29+
>>> # seconds_in_a_decade = 10*365*24*60*60
30+
>>> seconds_in_a_decade > 60000000
31+
True
32+
"""
33+
},
34+
{
35+
'code': r"""
36+
>>> # You're close! Perhaps you didn't account for leap years correctly.
37+
>>> # There were 2 leap years and 8 non-leap years in this period.
38+
>>> # Leap years have 366 days instead of 365.
39+
>>> 315360000 < seconds_in_a_decade < 331344000
40+
True
41+
"""
42+
},
43+
{
44+
'code': r"""
45+
>>> seconds_in_a_decade == 315532800
46+
True
47+
"""
48+
}
49+
]
50+
}
51+
]
52+
}

‎docs/install.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
Gofer Grader can be installed from git directly for now.
44

55
```bash
6-
pip install git+https://github.com/grading/gradememaybe.git
6+
pip install gofer-grader
77
```
88

99
Since both this package and the [okpy](https://pypi.org/project/okpy/) package

‎docs/ok-test-format.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ for this particular oktest.
5555

5656
## Example
5757

58-
Lets' walk through an example!
58+
Lets' walk through an example! See [usage documentation](using.md) for a demo Docker image of this example.
5959

6060
We want our students to find the total number of seconds in a decade &
6161
assign it to the variable `seconds_in_a_decade`. We want to progressively

‎docs/using.md‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Using Gofer Grader
22

3-
1. Write your tests in [ok test format](ok-test-format.html),
3+
1. Write your tests in [ok test format](ok-test-format.md),
44
and distribute them the same way you distribute lab notebooks
55
to students.
66
2. In the lab notebooks distributed to your students, import
@@ -19,6 +19,24 @@
1919
This will run the tests in `q1.py` with the student's
2020
current environment, and provide interactive results.
2121

22+
# Usage Demo
23+
24+
To test out Gofer Grader, we've provided a sample Docker image with a demo notebook and test file. Make sure Docker is installed and running on your computer.
25+
26+
In your terminal, run
27+
28+
```
29+
docker run -p 8888:8888 gavrilm/gofer-grader-demo
30+
```
31+
32+
This will download the demo image and start it in a new container, exposing port 8888 as the notebook server. Then, go to your browser and paste in the URL printed in the terminal to access the demo. It should be in the format:
33+
34+
```
35+
http://<ip address here>:8888?token=<token number here>
36+
```
37+
38+
\*Note: the IP address printed in the terminal may not be correct. Run `docker-machine ip` in the terminal for the correct one.\*
39+
2240
## Drop-in replacement for okpy
2341

2442
If you are currently using okpy in notebooks, you will

0 commit comments

Comments
 (0)