Merge pull request #14 from styx-api/add-getting-started-io

Add getting started / io chapter

Author: nx10

src/getting_started/io.md

@@ -1,22 +1,55 @@
-# I/O: Runner file handling
+# I/O: Runner File Handling
 
-TODO:
+When you're using Styx wrapper functions with the default runners, you won't have to worry too much about I/O since a lot of it gets handled automatically for you.
 
-- Explain output tuple, root attribute.
+## Basic File Access
 
-## _Default_ runner behaviour
+Take this example:
 
-While custom Styx runners allow users to implement file I/O handling any way they want, the 'default' runners (`LocalRunner` as well as `DockerRunner` and `SingularityRunner`) work very similarly by default.
+```python
+outputs = fsl.bet(infile="brain.nii", fractional_intensity=0.5)
 
-They create a directory (default path `styx_temp/` in the current working directory) in which a folder gets created for every Styx function call. These will look like this:
+outputs.mask_file  # File path to an individual output
+```
+
+The `outputs` object gives you structured access to generated files through properties that support autocompletion and include helpful documentation.
+
+## Dynamic File Access
+
+Sometimes, when a descriptor hasn't been fully implemented or if the output structure is more complex, an output property may not be available.. For these cases, you can use the `outputs.root` property, which always points to the output directory:
+
+```python
+outputs.root / "my_special_file.ext"
+
+# Dynamic file access
+for number in [1, 2, 3]:
+    f = outputs.root / f"my_file_with_a_{number}.ext"
+```
+
+## Default Runner Behavior
+
+While custom Styx runners let you implement file I/O handling however you want, the default runners (`LocalRunner`, `DockerRunner`, and `SingularityRunner`) all work pretty similarly by default. They create a working directory (defaults to `styx_temp/` in your current working directory) with individual folders for each Styx function call you make.
+
+### Directory Structure
 
 ```
 79474bd248c4b2f1_5_bet/
 ^^^^^^^^^^^^^^^^ ^ ^^^
 |                | |
-|                | `-- interface name (FSL BET)
-|                `---- number of execution (5th)
-`--------------------- unique random hash
+|                | `-- Interface name (FSL BET)
+|                `---- Execution number (5th call)
+`--------------------- Unique session hash
 ```
 
-Every time you create a new runner a new random hash will be generated. This ensures paths created are unique and avoid conflict with previous executions of your pipeline. The hash is followed by a counting number which chronologically will count up by one for every Styx function call. This makes the folder sortable. Lastly they contain the Styx function name to be human readable.
+**Components:**
+- **Session hash**: A unique random identifier generated per runner instance, preventing conflicts between pipeline executions
+- **Execution number**: Sequential counter for chronological ordering of function calls
+- **Interface name**: Human-readable identifier for the Styx function
+
+This naming convention ensures unique, sortable, and identifiable output directories.
+
+> [!WARNING]
+> You can clean up outputs using `shutil.rmtree(outputs.root)` for individual function outputs, or `shutil.rmtree(get_global_runner().data_dir)` to remove all outputs from the current session. **Be careful** - make sure you're not deleting any important data this way!
+
+> [!NOTE]
+> For advanced runner configuration and custom I/O behavior, see [Subcommands](./runners.md) and [Writing Custom Runners](../advanced_concepts/custom_runners.md).