Merge pull request #618 from dodona-edu/feat/docs-scratchpad

Add the Python sandbox student guide

Author: bmesuere

en/guides/students/exercises/index.md

@@ -39,6 +39,8 @@ On an exercise page, below the panel with the exercise description, there is a s
 
 ![Hand-in panel with an empty editor and the highlighted submit button](./handin-editor-en.png)
 
+For Python exercises, the `To sandbox` button next to the submit button opens [the Python sandbox](../scratchpad/), where you can run and debug your code in the browser before submitting it.
+
 ::: tip Use an IDE
 
 Although you can program directly in the editor on Dodona, we do not recommend solving all exercises there. Instead, we advise using an [Integrated Development Environment](https://en.wikipedia.org/wiki/Integrated_development_environment) (IDE). IDEs provide more support during the writing, execution, testing, and debugging of source code. This way, you learn to apply your programming skills generically to solve problems other than just the exercises on Dodona.

en/guides/students/index.md

@@ -14,5 +14,6 @@ If you are new to Dodona, follow the guides in this order:
 3. [Courses on Dodona](./courses/): register for a course, navigate its exercise series, and keep track of deadlines.
 4. [Solving Exercises](./exercises/): navigate to exercises, submit solutions, and ask questions about your code.
 5. [Understanding Feedback](./feedback/): interpret the submission statuses and the detailed feedback of the judge.
+6. [The Python Sandbox](./scratchpad/): run and debug Python code directly in your browser.
 
 Looking for a quick answer instead? The FAQ covers common questions about [accounts](/en/faq/accounts/), [questions and comments on your code](/en/faq/annotations/), and the [IDE plugins](/en/faq/ide-plugins/).

en/guides/students/scratchpad/feedback-debug-button-en.png

@@ -0,0 +1,74 @@
+---
+title: "The Python Sandbox"
+description: "Tutorial: running and debugging Python code directly in your browser"
+order: 6
+---
+
+# The Python Sandbox
+For Python exercises, Dodona has a built-in **sandbox**: a window in which you can write and run Python code directly in your browser, without installing anything on your computer. The sandbox is ideal for quickly trying something out: experiment with a few lines of code, test your solution with your own input, or step through your program with the built-in debugger to see exactly what it does. Code you run in the sandbox is **not** submitted to Dodona and is not evaluated by the judge; when you are happy with your code, you submit it in the usual way, as explained in [Solving Exercises](../exercises/).
+
+## Opening the Sandbox
+
+The sandbox is available on the page of every Python exercise. At the bottom of the panel where you submit your solution, next to the submit button, you will find the `To sandbox` button. Clicking it opens the `Python sandbox` in a panel on top of the exercise page.
+
+![Hand-in action bar with the To sandbox button next to Submit](./to-sandbox-button-en.png)
+
+The sandbox consists of two halves:
+
+- On the left you will find a **code editor** with a `Run` button, a field to provide **input**, and the **output** of your code.
+- On the right, the `Description` tab shows the exercise description, so you can keep reading the assignment while you write your code.
+
+If you had already written code in the editor of the exercise page, the sandbox automatically starts from that code. If the sandbox already contains different code from an earlier session, Dodona first asks whether you want to overwrite it with your latest changes.
+
+::: tip The first run can take a moment
+The sandbox runs Python entirely in your browser. The first time you run code, your browser still has to download and start the Python environment, so it can take a little while before you see any output. Subsequent runs are much faster.
+:::
+
+## Running Code
+
+Write your code in the editor on the left and click `Run`. The output of your program appears in the output panel below. While your code is running, you can interrupt it at any time with the `Stop` button.
+
+![Python sandbox with a short program, its produced output, and the input field](./sandbox-run-en.png)
+
+Some more things the sandbox can do:
+
+- **Input**: if your program reads input (for example with `input()`), you can simply type your answer in the input field when your program asks for it, and press enter. Prefer to prepare all input beforehand? Click `Switch to batch input` and enter all input lines in advance; `Switch to interactive mode` takes you back.
+- **Turtle graphics**: if your code draws with the `turtle` module, the drawing appears in a separate `Turtle` tab next to the textual output.
+- **Packages**: when your code imports a package, the sandbox automatically tries to install it. Most commonly used packages work; packages that need access to your operating system do not work in the browser.
+- **Files from the exercise**: files that come with the exercise can be loaded into the sandbox automatically, and you can drag links or images from the exercise description into the sandbox to use them in your code.
+
+## Submitting Your Code
+
+Code in the sandbox is never submitted automatically. Once your code does what you want, click `Finalize and submit`: this copies your code from the sandbox to the editor of the exercise page, where you can review it one last time and submit it. Only then is your solution evaluated by the judge, as described in [Understanding Feedback](../feedback/).
+
+::: warning Sandbox code is not saved
+Dodona does not store the code you write in the sandbox. If you close the page without copying your code to the editor and submitting it, your work may be lost. Submit regularly!
+:::
+
+## Debugging Step by Step
+
+The sandbox also contains a **debugger** (based on the well-known Python Tutor) that executes your program step by step. This is very useful if your program does something different from what you expected: instead of guessing, you can watch exactly what happens at each step.
+
+Click the `Debug` button next to `Run` to start the debugger. The right half of the sandbox switches to the `Debugger` tab, where you can walk through your program:
+
+- Drag the **slider** to move through the steps of your program, or use the arrow buttons to go to the previous, next, first or last step.
+- At each step, the debugger shows which line is being executed and how your program builds and stores information: the variables that exist at that point and their values.
+- Click `Stop debugging` to return to normal mode.
+
+![Debugger tab with the step slider, arrow buttons, the current step's variables, and the highlighted current line in the editor](./sandbox-debugger-en.png)
+
+### Debugging a Failed Test Case
+
+You can also start the debugger straight from the feedback on a submission. On the feedback page of a Python exercise, test cases show a `Debug` button. Clicking it opens the sandbox with the code of your submission, runs that specific test case with the same input the judge used, and opens the `Debugger` tab. Above the debugger, under `Test case being debugged`, you can see which test case you are stepping through. This way you can follow, step by step, exactly where your submission goes wrong for a failed test.
+
+![Test case on the feedback page with the Debug button](./feedback-debug-button-en.png)
+
+## Limitations
+
+The sandbox is a tool for experimenting, not a replacement for submitting:
+
+- Your code runs in your browser, not in the environment the judge uses. Running code in the sandbox never produces a submission, and only the judge determines whether your solution is correct.
+- Not all packages are available in the browser, and heavy computations may run slower than on the judge.
+- Sandbox code is not saved by Dodona: copy your code to the editor and submit it to keep it.
+
+The sandbox is only available for **Python** exercises. For other programming languages, we recommend working in an [IDE](../exercises/#submitting-a-solution) and submitting your solution on Dodona.

en/guides/students/scratchpad/index.md

@@ -39,6 +39,8 @@ Op een oefeningpagina staat onder het paneel met de beschrijving van de oefening
 
 ![Indieningspaneel met een lege editor en de gemarkeerde indienknop](./handin-editor-nl.png)
 
+Bij Python-oefeningen opent de knop `Naar sandbox` naast de indienknop [de Python-sandbox](../scratchpad/), waarin je je code in de browser kan uitvoeren en debuggen voor je ze indient.
+
 ::: tip Gebruik een IDE
 
 Alhoewel je perfect kan programmeren in de editor op Dodona zelf, raden we niet aan om alle oefeningen hierin op te lossen. In plaats daarvan adviseren we om een [Integrated Development Environment](https://nl.wikipedia.org/wiki/Integrated_development_environment) (IDE) te gebruiken. IDE's geven namelijk meer ondersteuning tijdens het schrijven, uitvoeren, testen en debuggen van broncode. Op die manier leer je je programmeervaardigheden generiek in te zetten om andere problemen aan te pakken dan enkel de oefeningen uit Dodona.

en/guides/students/scratchpad/sandbox-debugger-en.png

@@ -14,5 +14,6 @@ Ben je nieuw op Dodona? Volg dan de handleidingen in deze volgorde:
 3. [Cursussen op Dodona](./courses/): registreren voor een cursus, navigeren doorheen de oefeningenreeksen en deadlines opvolgen.
 4. [Oefeningen oplossen](./exercises/): navigeren naar oefeningen, oplossingen indienen en vragen stellen over je code.
 5. [Feedback begrijpen](./feedback/): de statussen van je oplossingen en de gedetailleerde feedback van de judge interpreteren.
+6. [De Python-sandbox](./scratchpad/): Python-code uitvoeren en debuggen rechtstreeks in je browser.
 
 Zoek je een snel antwoord? De FAQ behandelt veelgestelde vragen over [accounts](/nl/faq/accounts/), [vragen en opmerkingen bij je code](/nl/faq/annotations/) en de [IDE-plugins](/nl/faq/ide-plugins/).