Reorder to follow documentation structure

Documentation/.gitignore

@@ -0,0 +1 @@
+/.quarto/

Documentation/Vignettes/GettingStarted.qmd

@@ -0,0 +1,187 @@
+---
+title: "Getting Started with DeToX"
+description: "Starting using DeToX"
+author: Tommaso Ghilardi
+
+execute:
+  enabled: false
+---
+
+Great! You've got DeToX installed—now let's jump into the exciting part!
+
+This tutorial will walk you through an **EXTREMELY** basic example showing what DeToX can do and what you'll need to get started. Think of it as your quick-start guide to running your first eye-tracking experiment.
+
+::: callout-note
+## Before we begin
+
+This tutorial walks you through the essential steps for running an eye-tracking experiment with DeToX. We've designed it to be as straightforward as possible, though you'll need some basic familiarity with PsychoPy - specifically how to create windows and display stimuli. If you're new to PsychoPy or need a refresher, their [official tutorial](https://www.psychopy.org/coder/tutorial1.html) is an excellent starting point.
+
+Don't worry if you're not a PsychoPy expert! The concepts we'll use are fundamental and easy to pick up.
+:::
+
+DeToX bridges two powerful Python libraries: **PsychoPy** and **tobii_research**.
+
+-   **PsychoPy** is your experiment-building toolkit. It gives you the flexibility and control to design studies exactly how you want them—from simple reaction time tasks to complex visual paradigms.
+
+-   **tobii_research** is your direct line to Tobii eye trackers. It's incredibly powerful, but let's be honest—some of its low-level details can be... *complex*.
+
+**That's where DeToX comes in**: we've wrapped the tricky bits so you can focus on your research, not wrestling with SDK documentation.
+
+## Preparation
+
+let's begin importing the libraries that we will need for this example
+
+```{python}
+#| label: Libraries
+#| eval: false
+from psychopy import visual, core
+from DeToX import ETracker
+```
+
+**`visual`** and `core` are some of PsychoPy's main modules—it's what you'll use to create the window where your stimuli appear and your experiment runs.
+
+**`ETracker`** is DeToX's main class and your central hub for all eye-tracking operations. This is the object you'll interact with throughout your experiment to control calibration, recording, and data collection.
+
+## Window
+
+Every experiment needs a stage—in PsychoPy, that's your **Window**. This is where all your stimuli will appear and where participants will interact with your study.
+
+```{python}
+#| label: Window creation
+#| eval: false
+# Create the experiment window
+win = visual.Window(
+    size=[1920, 1080],  # Window dimensions in pixels
+    fullscr=True,       # Expand to fill the entire screen
+    units='pix'         # Use pixels as the measurement unit
+)
+```
+
+Breaking it down:
+
+-   **`size`**: Sets your window dimensions. Here we're using 1920×1080, but adjust this to match your monitor.
+
+-   **`fullscr=True`**: Makes the window take over the whole screen—crucial for experiments where you want to eliminate distractions.
+
+-   **`units='pix'`**: Defines how you'll specify positions and sizes throughout your experiment. DeToX supports multiple PsychoPy unit systems—`'height'`, `'norm'`, `'pix'`—so choose whichever you're most comfortable with or best fits your experimental design.
+
+::: callout-important
+## Window size
+
+If you're following along with this tutorial and experimenting on your own, we **strongly recommend** using a smaller window with `fullscr=False` instead of fullscreen mode. When `fullscr=True`, the window takes over your entire screen, making it tricky (or impossible!) to interact with your computer—like stopping the script or checking documentation. Save fullscreen for your actual experiments.
+:::
+
+Perfect now we have our window where we can draw images, videos and interact with them!!
+
+## ETracker
+
+So far we've focused on creating the canvas for our stimuli—but how do we actually interact with the eye tracker? Simple! We use the **`ETracker`** class we imported earlier.
+
+The `ETracker` needs access to the window we just created, so initializing it is straightforward:
+
+```{python}
+#| label: Et controller
+#| eval: false
+ET_controller = ETracker(win)
+```
+
+::: callout-important
+## Don't Have an Eye Tracker? No Problem!
+
+If you're following along without a Tobii eye tracker connected, you can still test everything using **simulation mode**. Just pass `simulate=True` when creating your `ETracker`:
+
+```{python}
+#| label: Et controller simulation
+#| eval: false
+ET_controller = ETracker(win, simulate=True)
+```
+
+This tells DeToX to collect data from your **mouse position** instead of an actual eye tracker—perfect for development, testing, or learning the workflow before you have hardware access 😉
+:::
+
+Once you run this code, DeToX will connect to your eye tracker and set everything up for you. It will also gather information about the connected device and display it in a nice, readable format:
+
+``` markdown
+┌────────────────── Eyetracker Info ──────────────────┐
+│Connected to the eyetracker:                         │
+│ - Model: Tobii Pro Fusion                           │
+│ - Current frequency: 250.0 Hz                       │
+│ - Current illumination mode: Default                │
+│Other options:                                       │
+│ - Possible frequencies: (30.0, 60.0, 120.0, 250.0)  │
+│ - Possible illumination modes: ('Default',)         │
+└─────────────────────────────────────────────────────┘
+```
+
+This tells us we're connected to the eye tracker and ready to start recording data!
+
+## Recod data
+
+Great! You're now connected to the eye-tracker (or simulating it). However, we're not actually collecting any data yet - let's fix that.
+
+To begin data collection, call the `start_recording` method on your ETracker instance:
+
+```{python}
+#| label: Recording
+#| eval: false
+# Start recording data
+ET_controller.start_recording(filename="testing.h5")
+```
+
+The `start_recording` method accepts a `filename` parameter for naming your data file. If you don't specify one, DeToX automatically generates a timestamp-based filename.
+
+Your eye-tracking data is now being collected continuously and will be later saved in a HDF5 format, which is ideal for storing large datasets efficiently. For details on the data structure and how to analyze your files, see our [DataFormats](DataFormats.qmd) guide.
+
+## Events
+
+OK, now that we're recording data, we can show images, videos, or whatever we want! It's entirely up to you and your experimental design!
+
+Since this is a **SUPER BASIC** example to get you started, we won't overcomplicate things with elaborate stimuli or complex tasks. Let's keep it stupidly simple. As we show images, videos or whatnot we need to keep track at which point thesee stimuli happen in our eyetracking data. And how to do so?? well we can use the `record_event` function!!
+
+```{python}
+#| label: Events
+#| eval: false
+# Send event 1
+ET_controller.record_event('wait 1')
+core.wait(2) # wait 2s
+
+# Send event 2
+ET_controller.record_event('wait 2')
+core.wait(2) # wait 2s
+```
+
+Here's what's happening:
+
+-   **`controller.record_event('wait 1')`**: Drops a timestamped marker labeled `'wait 1'` into your data stream. This is like planting a flag that says "something important happened HERE."
+
+-   **`core.wait(2)`**: Pauses execution for 2 seconds. During this time, the eye tracker keeps collecting gaze data in the background.
+
+-   **`controller.record_event('wait 2')`**: Plants another marker at the 2-second point, labeled `'wait 2'`.
+
+-   Another **`core.wait(2)`**: Waits another 2 seconds.
+
+Here we're just using `core.wait()` as a **placeholder**. In your actual experiment, this is where you'd display your stimuli—show images, play videos, present text, or run whatever task your study requires. The `record_event()` calls mark when those stimuli begin in this case!
+
+## Stop recording
+
+After the experiment is done, we need to stop the recording and save the data!!!
+
+```{python}
+#| label: Stop recording
+#| eval: false
+# Stop recording data
+ET_controller.stop_recording()
+```
+
+**Voilà!** DeToX will stop the recording and automatically save all your data to a file. You'll get another nice confirmation message showing you what happened:
+
+``` markdown
+┌────────────── Recording Complete ───────────────┐
+│Data collection lasted approximately 4.02 seconds│
+│Data has been saved to testing.h5                │
+└─────────────────────────────────────────────────┘
+```
+
+This tells you how long the recording session lasted and where your data file was saved. By default, DeToX creates a timestamped filename (like `testing.h5`) so you never accidentally overwrite previous recordings.
+
+**And that's it!** Your eye-tracking data—complete with all those event markers you recorded—is now safely stored and ready for analysis.

Documentation/Vignettes/Installation.qmd

@@ -0,0 +1,125 @@
+---
+title: "Installation"
+author: Tommaso Ghilardi
+---
+
+So you're interested in using DeToX? Awesome! Let's get you set up quickly.
+
+DeToX is designed as a lightweight wrapper around **PsychoPy** and **tobii_research**. Here's the good news: `tobii_research` usually comes bundled with PsychoPy, which means the only real hurdle is installing PsychoPy itself. And yes, PsychoPy *can* be a bit tricky to install due to its many dependencies—but don't worry, we'll walk you through it. Once PsychoPy is up and running, adding DeToX is a breeze.
+
+## Installing PsychoPy
+
+Since PsychoPy is the main challenge, let's tackle that first. You have **two main options**:
+
+-   **Package Installation**
+
+    Install PsychoPy like any other Python package using `pip`. This approach is flexible and ideal if you prefer working in an IDE (like **Positron**, **VS Code**, **PyCharm**, or **Spyder**) where you have full control over your Python environment.
+
+-   **Standalone Installation**
+
+    Use the PsychoPy standalone installer, which bundles PsychoPy and all its dependencies into a single, ready-to-use application. This is often the **easiest way to get started**, especially if you're not familiar with managing Python environments or just want to hit the ground running.
+
+We like installing psychopy as a package but you do you!
+
+::: panel-tabset
+### Package
+
+This method is ideal if you prefer working in an IDE (like Positron, VS Code, PyCharm, or Spyder) and want full control over your Python environment.
+
+#### Step 1: Create a Virtual Environment
+
+We like to use miniforge to handle our environments and Python installations. Any other method would work as well, but for simplicity we'll show you how we prefer to do it.
+
+*We recommend using Python 3.10 for the best compatibility:*
+
+``` bash
+mamba create -n detox_env python=3.10
+```
+
+This will create an environment called detox_env with python 3.10. Exactly what we need!
+
+You will probably need to confirm by pressing `y`, and after a few seconds you'll have your environment with Python 3.10! Great!
+
+#### Step 2: Activate Environment and Install PsychoPy
+
+Now let's activate this environment (making sure we're using it) and then install PsychoPy:
+
+``` bash
+mamba activate detox_env
+pip install psychopy
+```
+
+this will take some time but if you are lucky you will have psychopy in your enviroment
+
+Again, confirm if needed and you're done! Amazing!
+
+### Standalone
+
+PsychoPy is a large package with many dependencies, and sometimes (depending on your operating system) installing it can be quite tricky! For this reason, the PsychoPy website suggests using the standalone installation method. This is like installing regular software on your computer - it will install PsychoPy and all its dependencies in one go.
+
+#### Step 1: Install PsychoPy Standalone
+
+1.  Go to the [PsychoPy download page](https://www.psychopy.org/download.html)
+
+2.  Download the standalone installer for your operating system
+
+3.  Run the installer and follow the setup instructions
+
+You are done!!! Great!
+:::
+
+## Installing DeToX
+
+Once PsychoPy is installed, we can look at DeToX. Let's gets our hand dirty! The installation is the same for both the Package and Standalone PsychoPy installations but some steps differ.
+
+::: callout-warning
+## DeToX is Still in Development
+
+DeToX isn't yet available on PyPI, so you'll need to install it directly from our **GitHub repository**. Don't worry—it's straightforward, and we'll guide you through it!
+
+**One requirement:** You need **Git** installed on your system.
+
+📥 **Don't have Git?** Download it from [git-scm.com](https://git-scm.com/)—installation takes just a minute.
+:::
+
+::: panel-tabset
+### Package
+
+Again make sure to be in the correct environment if you installed PsychoPy as a package. with the following command:
+
+``` bash
+mamba activate detox_env
+```
+
+Then simply run:
+
+``` bash
+pip install git+https://github.com/DevStart-Hub/DeToX.git
+```
+
+Wait a few seconds, confirm if needed, and you are done!
+
+### Standalone
+
+1.  **Open PsychoPy**
+
+2.  **Go to Coder View** (the interface with the code editor)
+
+3.  **Open the Tools menu**
+
+4.  **Select "Plugins/package manager..."**
+
+5.  **Click on "Packages"** in the top tabs
+
+6.  **Click the "Open PIP terminal" button**
+
+7.  **Type the following command:** `pip install git+https://github.com/DevStart-Hub/DeToX.git`
+
+That's it! You now have both PsychoPy and DeToX installed and ready to use.
+:::
+
+::: callout-warning
+## Important: DeToX requires coding
+
+DeToX is a code-based library that works with PsychoPy's Coder interface. If you typically use PsychoPy's Builder (the drag-and-drop visual interface), you'll need to switch to the Coder interface to use DeToX. Don't worry - we provide plenty of code examples to get you started!
+:::