Skip to content

Commit ed7d866

Browse files
leogermondleogermond
committed
Merge branch 'build/quiz-improve-readme' into 'master'
quiz: Move README, and complete it See merge request feng/training/material!258
2 parents 68dde36 + d274d2c commit ed7d866

File tree

2 files changed

+101
-82
lines changed

2 files changed

+101
-82
lines changed

‎contrib/quiz.README.md

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# The Quiz tools
2+
3+
There are two tools related to scripts:
4+
5+
- `quiz.py`: Generates a quiz RST file from a valid "quiz directory"
6+
- `update_quiz.py`: Updates all the quiz RST files in the given directory tree.
7+
8+
# Principle
9+
10+
Quizzes are **templates** for standalone Ada projects with multiple variants.
11+
12+
Given a template, it is concretizable into several projects, one per
13+
choice. Those concrete projects will be *compile-run checked* by the tooling:
14+
those that compile and run without error will be considered correct answers.
15+
16+
There are 3 kinds of errors that can be detected
17+
18+
1. Project does not compile
19+
2. Project does compile but raises a run-time error
20+
3. Project does compile but raises a user error (`-gnata`)
21+
22+
NB: For the case of user errors, the `-gnata` flag will need to be provided in the
23+
associated gpr file.
24+
25+
Warning: Infinite loops or silent failures (return code is 0) are not detected by
26+
the tooling.
27+
28+
# Usage
29+
30+
The quizzes are meant to be used with the `contrib/quiz.py` script. This script
31+
takes an input file as argument and turns it into a Quiz slide in the training
32+
material's ReSTRuctured text idiom.
33+
34+
This is done by instanciating copies of the quiz project directory, one for each
35+
choice (A, B, C...), extracting the associated question, trying a compile-run of
36+
the answer's code, and marking it as an answer in case it compiled and ran
37+
correctly.
38+
39+
The output is saved as a *golden* .rst file and put into version control, so
40+
that the CI can double check the answer (using `contrib/quiz_update.py`), and
41+
validate that the result has not changed unexpectedly.
42+
43+
This allows for reviewers to focus on the rst result, and for maintainers to
44+
focus on the Ada code. As a result, the quiz is reviewed in its included form,
45+
which is not compilable, and the Ada code is saved as well, allowing for
46+
unambiguous reproducibility.
47+
48+
NB: Intermediate results could also be saved for similar reasons, but this is not
49+
the case today.
50+
51+
# Template's format
52+
53+
## adacut format
54+
55+
The template is based on the `adacut` generic format, used by `contrib/adacut.py`.
56+
It provides *directives* that are to be written as
57+
58+
```ada
59+
--$ directive type [target]
60+
```
61+
62+
* `directive` can be any of `begin`, `end`, `line`
63+
* `type` can be any of `cut`, `question`, `answer`
64+
* `target` can be any of `code`, `comment`, `all` (optional, `all` by default)
65+
66+
The directive indicates whether a `begin ... end` block is concerned or just the
67+
line that follows.
68+
69+
```ada
70+
--$ begin cut
71+
Toto : Integer;
72+
Titi : Integer;
73+
--$ end cut
74+
75+
--$ line cut
76+
Toto : Integer;
77+
```
78+
79+
The `cut` type is used to describe and answer, which will be *cut* into the
80+
template for the compile-run check.
81+
82+
First `cut` will be taken as the variant for choice A, second for choice B etc...
83+
84+
If `question` type is used, its content is included as part of the question, as
85+
a `.. code::` rst directive.
86+
If `answer` type is used, its content is included in the **answer** slide as an
87+
explaination paragraph, below the questions.
88+
89+
## Signifiant comments
90+
91+
The comment that is at the start of the file is considered to be the question and
92+
is included as-is (as raw rst).
93+
94+
If a cut **begin** with a comment, the text of the comment is used as the choice
95+
text **instead** of the code of the block.
96+
97+
If a cut **ends** with a comment, it is included as part of the answer in a special
98+
explaination block.

‎courses/fundamentals_of_ada/quiz/README.md

Lines changed: 3 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -5,86 +5,7 @@ This directory contain quizzes.
55
Quizzes are **templates** for standalone Ada projects with multiple variants.
66

77
Given a template, it is concretizable into several projects, one per
8-
choice. Those concrete projects will be *compile-run checked* by the tooling:
9-
those that compile and run without error will be considered correct answers.
8+
choice. Those concrete projects will be *compile-run checked* by the tooling.
109

11-
There are 3 kinds of errors that can be detected
12-
13-
1. Project does not compile
14-
2. Project does compile but raises a run-time error
15-
3. Project does compile but raises a user error (`-gnata`)
16-
17-
NB: For the case of user errors, the `-gnata` flag will need to be provided in the
18-
associated gpr file.
19-
20-
Warning: Infinite loops or silent failures (return code is 0) are not detected by
21-
the tooling.
22-
23-
# Usage
24-
25-
The quizzes are meant to be used with the `contrib/quiz.py` script. This script
26-
takes an input file as argument and turns it into a Quiz slide in the training
27-
material's ReSTRuctured text idiom.
28-
29-
This is done by instanciating copies of the quiz project directory, one for each
30-
choice (A, B, C...), extracting the associated question, trying a compile-run of
31-
the answer's code, and marking it as an answer in case it compiled and ran
32-
correctly.
33-
34-
The output is saved as a *golden* .rst file and put into version control, so
35-
that the CI can double check the answer (using `contrib/quiz_update.py`), and
36-
validate that the result has not changed unexpectedly.
37-
38-
This allows for reviewers to focus on the rst result, and for maintainers to
39-
focus on the Ada code. As a result, the quiz is reviewed in its included form,
40-
which is not compilable, and the Ada code is saved as well, allowing for
41-
unambiguous reproducibility.
42-
43-
NB: Intermediate results could also be saved for similar reasons, but this is not
44-
the case today.
45-
46-
# Template's format
47-
48-
## adacut format
49-
50-
The template is based on the `adacut` generic format, used by `contrib/adacut.py`.
51-
It provides *directives* that are to be written as
52-
53-
```ada
54-
--$ directive type [target]
55-
```
56-
57-
* `directive` can be any of `begin`, `end`, `line`
58-
* `type` can be any of `cut`, `question`, `answer`
59-
* `target` can be any of `code`, `comment`, `all` (optional, `all` by default)
60-
61-
The directive indicates whether a `begin ... end` block is concerned or just the
62-
line that follows.
63-
64-
```ada
65-
--$ begin cut
66-
Toto : Integer;
67-
Titi : Integer;
68-
--$ end cut
69-
70-
--$ line cut
71-
Toto : Integer;
72-
```
73-
74-
The `cut` type is used to describe and answer, which will be *cut* into the
75-
template for the compile-run check.
76-
77-
First `cut` will be taken as the variant for choice A, second for choice B etc...
78-
79-
If `question` type is used, its content is included as part of the question, as
80-
a `.. code::` rst directive.
81-
If `answer` type is used, its content is included in the **answer** slide as an
82-
explaination paragraph, below the questions.
83-
84-
## Signifiant comments
85-
86-
The comment that is at the start of the file is considered to be the question and
87-
is included as-is (as raw rst).
88-
89-
If a cut **ends** with a comment, it is included as part of the answer in a special
90-
explaination block.
10+
See `contrib/quiz.README.md` for a helper on the tools, and the format of the files
11+
in the current directory

0 commit comments

Comments
 (0)