[documentation] Broken link / lacking explanation / inconsistencies re: environments in task_tuto.rst

[phlummox]

Describe the bug

In the "latest" version of https://docs.inginious.org/en/latest/teacher_doc/task_tuto.html, 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 https://docs.inginious.org/en/latest/teacher_doc/task_tuto.html

   "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 https://docs.inginious.org/en/latest/teacher_doc/task_tuto.html:

  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. 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).

[nrybowski]

@phlummox Thanks for the feedback. The documentation is clearly not up-to-date, we will definitively take into account your comments.