INGInious / INGInious/INGInious
[documentation] Broken link / lacking explanation / inconsistencies re: environments in task_tuto.rst
- Dominant language
- Python
- Stars
- 241
- Forks
- 151
- Avg merge
- 5d 15h
- Merged PRs (30d)
- 5
Description
**Describe the bug**
In the "latest" version of , which I assume is generated from `doc/teacher_doc/task_tuto.rst`:
- There's a broken link to `create_container`.
- It's not clear exactly what environments are, what values are permissible in
the `environment` key of a "task.yaml" file, and where INGinious gets a list of allowable values from.
- The documentation seems to be inconsistent with the behaviour of the system when run using the sample docker-compose.yml file which README.rst suggests be used.
- I've reported both the behaviour of the system, and the documentation, here, as I'm not sure which is supposed to be correct.
**INGInious installation details**
- Version: ad7ab7214eff7094c39d6c445b24786f090221df
- Containers version (if applicable): N/A, I think - using `docker compose up --build`, so should be same as above version
**To Reproduce**
Steps to reproduce the behavior:
1. Clone the repo, check out ad7ab7214eff7094c39d6c445b24786f090221df
2. Run containers using `docker compose up --build`
3. Log in as superadmin/superadmin, create a course (e.g. "mycourse")
4. Use the web UI to add a task - as suggested by
"Tasks" / "List of exercises" / "add tasks"; enter e.g. "mytask" in modal box
and click "create new task".
As per the instructions, "set the task name to Hello World! and put some context and author name. **Container setup can be left with default parameters.**" [my emphasis]
**Expected behavior**
- The relevant bits of .rst file are around
https://github.com/INGInious/INGInious/blob/ad7ab7214eff7094c39d6c445b24786f090221df/doc/teacher_doc/task_tuto.rst?plain=1#L62
- In the documentation at :
Instead of the bare, unhyperlinked text "Please see create_container", there should be a link to relevant documentation about containers. (Has this perhaps been moved to another section? Since the markup in the .rst file does not result in a hyperlink on the docs.inginious.org site.)
- It would be helpful to give even a brief explanation of what kinds of environments are typically acceptable, and where INGinious gets a list of valid environments from.
- If one follows the instructions - "Container setup can be left with default parameters" - then the system in fact creates a task.yaml file containing
```
environment_id: mcq
environment_parameters: {}
environment_type: mcq
```
My understanding is that for a Python "Hello world" task like the documentation is describing, MCQ is almost certainly not what one wants. Does the documentation need to be updated, so that a user is guided to set up a more sensible environment? Alternatively, should the system have a different default environment? (MCQ doesn't seem like a good default.)
- The file snippet included under the heading "Manual" is inconsistent with what's created by the UI. It suggests creating a task.yaml file containing the line
```
environment: default
```
but the current version of INGinious seems to require `environment_id`, `environment_parameters` and `environment_type` keys.
**Screenshots**
N/A
**Desktop (please complete the following information):**
- OS: Mint Linux
- Browser: Vivaldi
- Version: 7.4.3684.38
**Additional context**
Currently, using docker compose is _the_ recommended way of trying out INGinious, as per the [README](https://github.com/INGInious/INGInious/blob/ad7ab7214eff7094c39d6c445b24786f090221df/README.rst). But if users are likely to need to know how to add or configure environments besides those built into the docker-compose.yml file, it might be worth mentioning that (either in the README, or as a comment in YML file).
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.