From 931551eef602034b0950aaaf92b8a84875eeac7e Mon Sep 17 00:00:00 2001 From: Antti Leinonen Date: Fri, 28 Mar 2025 17:15:46 +0200 Subject: [PATCH] Add documentation for course options --- docs/course_options.md | 61 ++++++++++++++++++++++++++++++++++++++++++ docs/tmcproject.md | 3 +++ 2 files changed, 64 insertions(+) create mode 100644 docs/course_options.md diff --git a/docs/course_options.md b/docs/course_options.md new file mode 100644 index 00000000000..748078371f4 --- /dev/null +++ b/docs/course_options.md @@ -0,0 +1,61 @@ +# Course configuration options + +The course can be configured as a whole using a configuration file called `course_options.yml`. + +`course_options.yml` has to be in the root directory of the repository and may contain the following configurations: + +- **`hidden`** hides the course from students (including in web UI and IDEs). +- **`hide_after`** hides the course after a given date from students (including in web UI and IDEs) and refuses to accept any more submissions. +- **`hidden_if_registered_after`** hides the course from students (including in web UI and IDEs) who have registered after the given date. After the given date it will also be invisible to unregistered users. +- **`locked_exercise_points_visible`** tells whether exercises that one has not unlocked are visible on the scoreboard. Defaults to true. +- **`formal_name`** course formal name to be used in certificates. Makes it easier to use the same template and repository for multiple courses. +- **`paste_visibility`** determines who can access pastes for submissions. Possible values: + - `open` (default value): + - In the first 2 hours after submission, the paste is visible to: + - The submission owner. + - Teachers and course assistants. + - Users who have completed the exercise. + - Anyone, if the submission did not pass all tests. + - After 2 hours, the paste is only visible to: + - The submission owner. + - Users who have completed the exercise. + - Teachers and course assistants. + - `protected`: Visible only to: + - The user who submitted it. + - Teachers and course assistants. + - `no-tests-public`: + - In the first 2 hours after submission, the paste is visible to everyone. + - After 2 hours, it is only visible to: + - The submission owner. + - Teachers and course assistants. + - `everyone`: Always visible to everyone. + - `completed-only`: Only visible to: + - Users who have completed the exercise. + - The submission owner. + - Teachers and course assistants. +- **`certificate_downloadable`** makes the certificate downloadable. Defaults to false. +- **`certificate_unlock_spec`** makes the certificate downloadable only after the given condition is met. If `certificate_downloadable` is false then it overrides this. See below for more. + +If there are multiple unlock conditions, then all of them must be met for the exercise to be unlocked. + +The full syntax of a `certificate_unlock_spec` condition is as follows: + +- `exercise [group] ` +- `point[s] ` +- `% [in|of|from] ` +- ` point[s] ` +- ` exercise[s] [in|of|from] ` +- `` + +Here's an example configuration file: + +```yaml +hidden: true +hide_after: 2010-02-15 +hidden_if_registered_after: 2010-01-01 +locked_exercise_points_visible: false +formal_name: "Object Oriented Programming – part 1" +paste_visibility: open +certificate_downloadable: true +certificate_unlock_spec: 80% of week1 +``` diff --git a/docs/tmcproject.md b/docs/tmcproject.md index 861b7ad1a71..6a4079b872d 100644 --- a/docs/tmcproject.md +++ b/docs/tmcproject.md @@ -1,5 +1,8 @@ Exercises can be configured by adding an optional `.tmcproject.yml` file to the exercise root directory. Additionally, a course-wide file can be added to the course's root. When the course is then refreshed, the course-wide file is merged with the exercise-specific ones for the exercise stub and solution. For each key-value pair in the course-wide file, if the key is not present in the exercise-specific file, it is added to it with the course-wide file's value. + +A course can also be configured as a whole using a `course_options.yml`-configuration file, documentation for that can be found [here](./course_options.md). + ## Keys All of the keys listed below are optional.