diff --git a/docs/Users/EmioLabs/create-your-lab.md b/docs/Users/EmioLabs/create-your-lab.md index 36d5561..9ad5f13 100644 --- a/docs/Users/EmioLabs/create-your-lab.md +++ b/docs/Users/EmioLabs/create-your-lab.md @@ -95,7 +95,7 @@ We also added extensions to the original Markdown to ease the making of labs. These elements extend the basic syntax by adding additional features. It will only be understood by this application. -We use nested fenced block principle to define our custom blocks. A block fence is a sequence of at least three consecutive `:`. The content of the fenced block consists of all subsequent lines, until a closing block fence with at least as many `:` as the opening block fence. +We use *nested fenced block* principle to define our custom blocks. A block fence is a sequence of at least three consecutive `:`. The content of the fenced block consists of all subsequent lines, until a closing block fence with at least as many `:` as the opening block fence. If you want to nest multiple fenced blocks, the parent block fence should have more `:` than the children. For example : @@ -107,6 +107,86 @@ MY_CONTENT :::: <-- end of parent ``` +#### Buttons + +There are three types of buttons available : + +1. The __runsofa-button__ will launch a SOFA simulation with the specified scene file `MY_SCENE.py`. You can pass as many arguments as you want to the scene file: + ```markdown + #runsofa-button(file="assets/labs//MY_SCENE.py",  + pyargs=["MY_ARGUMENT_1", "MY_ARGUMENT_2"]) + ``` +2. The __python-button__ will run a python script `MY_SCRIPT.py`. You can optionally provide a path to additional python modules that will be added to the `PYTHONPATH` before running the script. + ```markdown + #python-button(file="assets/labs//MY_SCRIPT.py", + pyargs=["arg1", "example/path/as/arg2"],  + extrapythonpath=["OPTIONAL_PATH_TO_PYTHON_MODULES"]) + ``` + You can use this button to install extra Python packages for your lab with: + ```markdown + #python-button(pyargs=["-m", "pip", "install", "--target", "assets/labs//modules/site-packages", "-r", "assets/labs//requirements.txt"]) + ``` +3. The __open-button__ will open a file `MY_FILE` with the default application associated with the file type on your system. + ```markdown + #open-button(file="assets/labs//MY_FILE") + ``` + +An argument can be a value of a [`select block`](#select-block) or an [`input`](#text-input) field, by using its unique name that you defined. For example: + +```markdown +#runsofa-button(file="MY_SCENE.py", + pyargs=["MY_UNIQUE_SELECT_OR_INPUT_NAME", "MY_ARGUMENT_2"]) +``` + +#### Collapsible Block + +Create collapsible section with the following block fence with the keyword `collapse` : + +```markdown +::: collapse MY_TITLE +MY_CONTENT +::: +``` + +#### Exercise Block + +You can highlight your exercises by using the following block fence with the keyword `exercise` : + +```markdown +::: exercise +MY_EXERCISE_CONTENT +::: +``` + +#### Highlighted block + +You can highlight some text by using the following block fence with the keyword `highlight` : + +```markdown +::: highlight +MY_CONTENT +::: +``` + +#### Icons +We use the icon library [font awesome](https://fontawesome.com/icons). You can browse and copy the name of a free icon to put into the Markdown command: + +```markdown +#icon("ICON_NAME") +``` + +For example: +```markdown +#icon("warning") <-- will display a warning icon +``` + +#### Include +You can include the content of another markdown file with the following syntax: + +```markdown +#include("assets/labs//MY_MARKDOWN_FILE.md") +``` + #### Quiz You can create a quiz with **open answer** or a **multiple choice question**. For an open answer, create a block fence with the keyword `quiz`. Inside the quiz fence block, create another block fence with the keyword `question`, followed by your question (on the same line) and the answer on the next line, inside the block fence. For example : @@ -150,62 +230,74 @@ This will give the following : Example of a multiple choice question after submission. The correct answers are highlighted in green, the wrong one in red.
After submitting the answer.
-#### Video -You can add videos by using the following container : +#### Select Block + +Create select content with the following block fence with the keyword `select`. +Inside the select block, you can define options with the keyword `option` followed by the value for the option. Each option should have a unique value. +You can optionally add a label to the option by using the syntax `[MY_LABEL]`For example: ```markdown -#main-video("PATH_OR_URL_TO_MY_VIDEO") -#video("PATH_OR_URL_TO_MY_VIDEO") +:::: select MY_UNIQUE_SELECT_NAME +::: option MY_OPTION_VALUE_1 [MY_LABEL_1] +::: option MY_OPTION_VALUE_2 +::: option MY_OPTION_VALUE_3 [MY_LABEL_3] +:::: ``` -The `main-video` will move to the bottom right corner of the application when scrolling down. Only one `main-video` should be used in a lab (including main and other markdown files). +You may have as many options as you want. -#### Highlighted block +#### Solutions +You can hide solutions in a collapsible block with the keyword `solution`. A solution command will display a "Solution" collapse. When clicking on it, the content of the solution will be displayed. +Don't forget to enable the solution mode in Emio Labs to see the solutions in the app. You can toggle it in **Labs>Enable/Disable Solutions** in the top menu bar of the app. -You can highlight some text by using the following block fence with the keyword `highlight` : +It exists two ways to include solutions in your lab: +- the inline +- the solution block -```markdown -::: highlight -MY_CONTENT +:::info +The labs that come with Emio Labs will look for the solution files in the solutions directory `path/to/home/emio-labs/VERSION/assets/solutions/LAB_NAME/`. Make sure to put the solution files in this directory. ::: -``` -#### Exercise Block +##### Inline Solution +The content of the solution is given by the markdown file `MY_SOLUTION.md` and the solution block with the id `MY_SOLUTION_ID` in this markdown file. For example, if the solution file contains +`#solution(file="assets/solutions//MY_SOLUTION.md", id="MY_SOLUTION_ID")`, it will display the content of the solution block with the id `MY_SOLUTION_ID` in the file `MY_SOLUTION.md`. -You can highlight your exercises by using the following block fence with the keyword `exercise` : -```markdown -::: exercise -MY_EXERCISE_CONTENT -::: -``` +The content of the file `MY_SOLUTION.md` should be a list of `solution blocks` with IDs with `MY_SOLUTION_ID` among them. -#### Collapsible Block +`MY_SOLUTION.md` example: -Create collapsible section with the following block fence with the keyword `collapse` : ```markdown -::: collapse MY_TITLE -MY_CONTENT +## A title that won't be in the solution. + +::: solution MY_SOLUTION_ID +MY_SOLUTION_CONTENT_IN_MARKDOWN +::: + +Some text that won't be in the solution. + +::: solution exercise-1 +MY_SOLUTION_CONTENT_IN_MARKDOWN_FOR_EXERCISE_1 ::: ``` -#### Select Block -Create select content with the following block fence with the keyword `select`. -Inside the select block, you can define options with the keyword `option` followed by the value for the option. Each option should have a unique value. -You can optionally add a label to the option by using the syntax `[MY_LABEL]`For example: +##### Solution Block +The content of the solution is directly written in the markdown file, inside a block fence with the keyword `solution`. For example: -```markdown -:::: select MY_UNIQUE_SELECT_NAME -::: option MY_OPTION_VALUE_1 [MY_LABEL_1] -::: option MY_OPTION_VALUE_2 -::: option MY_OPTION_VALUE_3 [MY_LABEL_3] -:::: -``` + ```markdown + :::: solution MY-UNIQUE-ID + MY_SOLUTION_CONTENT_IN_MARKDOWN + :::: + ``` -You may have as many options as you want. + ```markdown + :::: solution MY-UNIQUE-ID + #include("assets/solutions//MY_SOLUTION.md") + :::: + ``` #### Text Input You can add an text input field with: @@ -226,49 +318,16 @@ For example: Example of an input field with the placeholder and a value.
Input example. (left) Placeholder. (right) Value.
-#### Buttons - -There are three types of buttons available : - -1. The __runsofa-button__ will launch a SOFA simulation with the specified scene file `MY_SCENE.py`. You can pass as many arguments as you want to the scene file: - ```markdown - #runsofa-button(file="assets/labs//MY_SCENE.py",  - pyargs=["MY_ARGUMENT_1", "MY_ARGUMENT_2"]) - ``` -2. The __python-button__ will run a python script `MY_SCRIPT.py`. You can optionally provide a path to additional python modules that will be added to the `PYTHONPATH` before running the script. - ```markdown - #python-button(file="assets/labs//MY_SCRIPT.py", - pyargs=["arg1", "example/path/as/arg2"],  - extrapythonpath=["OPTIONAL_PATH_TO_PYTHON_MODULES"]) - ``` - You can use this button to install extra Python packages for your lab with: - ```markdown - #python-button(pyargs=["-m", "pip", "install", "--target", "assets/labs//modules/site-packages", "-r", "assets/labs//requirements.txt"]) - ``` -3. The __open-button__ will open a file `MY_FILE` with the default application associated with the file type on your system. - ```markdown - #open-button(file="assets/labs//MY_FILE") - ``` - -An argument can be a value of a [`select block`](#select-block) or an [`input`](#text-input) field, by using its unique name that you defined. For example: - -```markdown -#runsofa-button(file="MY_SCENE.py", - pyargs=["MY_UNIQUE_SELECT_OR_INPUT_NAME", "MY_ARGUMENT_2"]) -``` - -#### Icons -We use the icon library [font awesome](https://fontawesome.com/icons). You can browse and copy the name of a free icon to put into the Markdown command: +#### Video -```markdown -#icon("ICON_NAME") -``` +You can add videos by using the following container : -For example: ```markdown -#icon("warning") <-- will display a warning icon +#main-video("PATH_OR_URL_TO_MY_VIDEO") +#video("PATH_OR_URL_TO_MY_VIDEO") ``` +The `main-video` will move to the bottom right corner of the application when scrolling down. Only one `main-video` should be used in a lab (including main and other markdown files). ## Share Your Labs