You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/source/question-format.md
+37-38Lines changed: 37 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,7 @@ describes that JSON, and how to build it from Python without a source document.
8
8
A {class}`~in2lambda.api.set.Set` holds {class}`~in2lambda.api.question.Question` objects, each
9
9
holding {class}`~in2lambda.api.part.Part` objects, each holding the
10
10
{class}`~in2lambda.api.response_area.ResponseArea` boxes students type into.
11
-
{meth}`~in2lambda.api.set.Set.to_json` writes the lot.
11
+
{meth}`~in2lambda.api.set.Set.to_json` writes the set as JSON.
12
12
13
13
```pycon
14
14
>>> from in2lambda.api.part import Part
@@ -66,8 +66,8 @@ holding {class}`~in2lambda.api.part.Part` objects, each holding the
66
66
67
67
```
68
68
69
-
{meth}`~in2lambda.api.set.Set.to_json` writes a folder named after the set, and a zip of it to
70
-
upload:
69
+
{meth}`~in2lambda.api.set.Set.to_json` writes a folder named after the set, and a zip of that
70
+
folder to upload:
71
71
72
72
```pycon
73
73
>>> import json, os, tempfile
@@ -87,24 +87,23 @@ upload:
87
87
88
88
```
89
89
90
-
A few things the example shows in passing:
90
+
The example also shows the following:
91
91
92
-
-**Building parts directly beats the incremental helpers.**[Filters](filters/index)
93
-
read a document in order, so they call
92
+
-**Pass `Part` objects to `Question` where the script holds the whole question.**
93
+
[Filters](filters/index)read a document in order, so they call
94
94
{meth}`~in2lambda.api.question.Question.add_part_text` and
95
95
{meth}`~in2lambda.api.question.Question.add_solution`, which fill in whichever part comes next.
96
-
A script that already knows the whole question should pass `Part` objects to `Question`, as
97
-
above; only those give a part a final answer or an answer box.
98
-
-**A line holding only `---` (or `***`) splits a worked solution** into the steps students go
99
-
through one at a time in the structured tutorial.
100
-
-**Unset question settings are left out of the JSON** rather than guessed at, so `skill`,
101
-
`guidance` and the two durations only appear when set. `publish` and the four `display_*`
102
-
settings always do, defaulting to `True`.
103
-
-**Images** go in `Question.images` as paths on disk; they are copied into `media/` under the file
104
-
name they already had, and every reference to one in the question's markdown is rewritten to that
105
-
name, which is all Lambda Feedback looks an image up by.
96
+
A `Part` object gives a part a final answer and an answer box, which those two methods do not.
97
+
-**A line holding only `---` (or `***`) splits a worked solution** into the steps the
98
+
structured tutorial shows students one at a time.
99
+
-**Unset question settings are left out of the JSON**, so `skill`, `guidance` and the two
100
+
durations appear only when set. `publish` and the four `display_*` settings always appear, and
101
+
default to `True`.
102
+
-**Images** are paths on disk listed in `Question.images`. `to_json` copies each image into
103
+
`media/` under its own file name, and rewrites every reference to that image in the question's
104
+
markdown to the same name. Lambda Feedback looks an image up by that name alone.
106
105
-**{meth}`Set.from_json <in2lambda.api.set.Set.from_json>`** reads an existing export, as a folder
107
-
or a zip, so an edit to a real set can start from what Lambda Feedback produced.
106
+
or a zip, so an edit to a real set starts from the export Lambda Feedback produced.
108
107
109
108
## The JSON in2lambda writes
110
109
@@ -116,12 +115,13 @@ A few things the example shows in passing:
116
115
<set name>.zip # the folder, zipped, to upload
117
116
```
118
117
119
-
A question's filename is its title with spaces and the characters Windows and path separators
120
-
forbid (`/ \ < > : " | ? *`) each replaced by an underscore. An image keeps the file name it
121
-
already had, so `images=["figures/rocket-momentum.png"]` gives `media/rocket-momentum.png`, and the
122
-
references to it are rewritten to that name. `media/` is one flat folder for the whole set, so a
123
-
file two questions use is copied once, and a second file of a name already taken is named as Lambda
124
-
Feedback names one, `question_001_<Title>_0001.png`. Files are written on a single line.
118
+
A question's filename is its title, with spaces and the characters Windows and path separators
119
+
forbid (`/ \ < > : " | ? *`) each replaced by an underscore. An image keeps its own file name, so
120
+
`images=["figures/rocket-momentum.png"]` gives `media/rocket-momentum.png`, and every reference to
121
+
that image is rewritten to `rocket-momentum.png`. `media/` is one flat folder for the whole set: a
122
+
file two questions use is copied once, and a second file whose name is already taken is named as
123
+
Lambda Feedback names an image, `question_001_<Title>_0001.png`. Each JSON file is written on a
124
+
single line.
125
125
126
126
### Set
127
127
@@ -154,33 +154,32 @@ The three types in2lambda writes:
154
154
|`NUMERIC_UNITS`|`comparePhysicalQuantities`| a number and a unit, e.g. `0.106 kg`|`gradeParams` holds `rtol` (and `strict_syntax`); `config` is null |
155
155
|`MULTIPLE_CHOICE`|`arrayEqual`| a list of booleans, one per option |`config` holds `single`, `options` and `randomise`; `gradeParams` is null |
156
156
157
-
The three lists an area carries, each a dataclass in
157
+
A response area holds three lists, each of a dataclass in
158
158
{mod}`in2lambda.api.response_area`:
159
159
160
160
-`inputSymbols` — `{"symbol", "code", "aliases", "isVisible"}` from
161
-
{class}`~in2lambda.api.response_area.InputSymbol`. `symbol`is what students see
162
-
(e.g. `\(\rho\)`), `code` what the evaluation function reads.
161
+
{class}`~in2lambda.api.response_area.InputSymbol`. Lambda Feedback displays `symbol`to students
162
+
(e.g. `\(\rho\)`), and the evaluation function reads`code`.
163
163
-`tests` — `{"id", "payload", "expectedResponse": {"isCorrect"}}` from
164
164
{class}`~in2lambda.api.response_area.Test`: the author's own checks of the marking.
165
165
-`cases` — `{"id", "answer", "feedback", "isCorrect", "params"}` from
166
166
{class}`~in2lambda.api.response_area.Case`: a response matching `answer` is shown `feedback`,
167
167
and may be marked correct.
168
168
169
-
An `id` left unset is a fresh UUID, which is what import needs.
169
+
An `id` left unset is written as a fresh UUID, which import requires.
170
170
171
171
### Markdown
172
172
173
-
Maths is `$...$` inline and `$$` on its own lines for display, rendered by
174
-
[KaTeX](https://katex.org/): commands KaTeX lacks do not display — degrees, for example, are
175
-
written `^\circ`. An image is written ``, naming the file as it
176
-
sits in `media/`. A filter passes through whatever path the source document used, so
This page gives a quick overview of how to get started with in2lambda to quickly add documents to Lambda Feedback.
3
+
This page describes how to install in2lambda and convert a document into a Lambda Feedback question set.
4
4
5
5
## 1. Installation
6
6
7
7
### Docker
8
8
9
9
[](https://github.com/lambda-feedback/in2lambda/pkgs/container/in2lambda)
10
10
11
-
The following creates an interactive container which includes in2lambda and mounts the current working directory into`/files`:
11
+
The following command starts an interactive container holding in2lambda, with the current working directory mounted at`/files`:
12
12
13
13
```bash
14
14
$ docker run -it --rm -v $(pwd):/files ghcr.io/lambda-feedback/in2lambda sh
15
15
```
16
16
17
-
Within the container, we can access the files and run in2lambda as normal.
17
+
Run in2lambda over those files inside the container.
18
18
19
19
```bash
20
20
$ cd files
@@ -23,15 +23,15 @@ $ ...
23
23
$ exit
24
24
```
25
25
26
-
The container is stopped and deleted after exiting, although the image remains downloaded for future use.
26
+
Docker stops and deletes the container on exit. The image stays on disk for the next run.
This can also be done through [pipx](https://pypa.github.io/pipx/).
47
+
[pipx](https://pypa.github.io/pipx/) installs in2lambda as well.
48
48
49
49
## 2. Choose a Document
50
50
51
-
`in2lambda convert` takes in two arguments:
51
+
`in2lambda convert` takes two arguments:
52
52
53
53
- The path to a document.
54
-
- A filter describing how to parse it.
54
+
- A filter describing how to parse that document.
55
55
56
-
A list of available filters can be found [here](filters/index).
56
+
The [filters page](filters/index) lists every filter.
57
57
58
-
For instance, the following takes in`questions.tex`and uses a filter that expects [each part to be directly followed by the solution](filters/_autosummary/PartSolPartSol):
58
+
The following command reads`questions.tex`with a filter that expects [each part to be followed by its solution](filters/_autosummary/PartSolPartSol):
59
59
60
60
```bash
61
61
$ in2lambda convert questions.tex PartSolPartSol
62
62
```
63
63
64
64
:::{note}
65
-
The filter name is case-insensitive. Don't worry about the capital letters.
65
+
The filter name is case-insensitive.
66
66
:::
67
67
68
-
Another filter might be used if [the answers are in a separate file](filters/_autosummary/PartsSepSol):
68
+
A different filter reads [answers held in a separate file](filters/_autosummary/PartsSepSol):
69
69
70
70
```bash
71
71
$ in2lambda convert questions.tex -a solutions.tex PartsSepSol
72
72
```
73
73
74
-
By default, this generates an `out` directory in the same place that the command was run in. It contains the zipped question files.
74
+
`in2lambda convert` writes an `out` directory in the directory the command ran in, holding the zipped question files.
75
75
76
-
Before writing anything, in2lambda prints the problems it can detect that would stop the set importing or make it render wrongly — an answer that doesn't fit the box marking it, a figure the export won't contain, maths that KaTeX can't display. Each names the question, part and field to go and look at. They are warnings rather than errors: the `out` directory is written either way, since a problem found here may well be deliberate.
76
+
Before writing that directory, in2lambda prints the problems that would stop Lambda Feedback importing the set or would render it wrongly: an answer that does not fit the box marking it, a figure the export would not contain, maths KaTeX cannot display. Each problem names the question, the part and the field holding it. Each problem is a warning, and in2lambda writes the `out` directory whatever it finds, because an author may have intended the problem.
77
77
78
-
The maths is checked by rendering it with KaTeX itself, the way Lambda Feedback will, which needs [Node.js](https://nodejs.org) installed. Without Node.js everything else is still checked and in2lambda says the maths was not.
78
+
in2lambda checks the maths by rendering it with KaTeX, as Lambda Feedback renders it, which needs [Node.js](https://nodejs.org). Without Node.js, in2lambda runs the other checks and reports that it did not check the maths.
79
79
80
-
With [xelatex](https://tug.org/texlive/) installed alongside pandoc, the set is also compiled the way Lambda Feedback makes a PDF of it, and any LaTeX error names the field it is in. Without it, one warning says which packages to install instead.
80
+
With [xelatex](https://tug.org/texlive/) installed alongside pandoc, in2lambda also compiles the set as Lambda Feedback compiles a PDF of it, and names the field holding each LaTeX error. Without xelatex, in2lambda prints one warning naming the packages to install.
81
81
82
-
Check the [command line tool reference](reference/command-line)for more information.
82
+
The [command line reference](reference/command-line)describes every command and option.
83
83
84
84
## 3. Import into Lambda Feedback
85
85
86
-
Click on a set in teacher mode. The arrow next to the "Add Question" button allows you to import a question from a file.
86
+
Open a set in teacher mode. The arrow beside the "Add Question" button imports a question from a file.
87
87
88
-
Choose the zip file you wish to upload, and the question should appear! 🎉
88
+
Choose the zip file to upload, and Lambda Feedback adds the question to the set.
89
89
90
-
Imported questions arrive published with every display setting on, and the set's own visibility settings still apply. The Python API can set each of these per question — see the
90
+
An imported question arrives published, with every display setting on, and the set's own visibility settings apply to it. The Python API sets each of these per question; see the
91
91
[question format](question-format).
92
92
93
93
0 commit comments