docs: document utility helpers

Author: zh1peng

docs/index.rst

@@ -27,6 +27,7 @@ Start with one of the tutorials below or explore the API reference.
    tutorials/build_stimulus
    tutorials/send_trigger
    tutorials/cli_usage
+   tutorials/utilities
 
 
 .. toctree::

docs/tutorials/utilities.md

@@ -0,0 +1,47 @@
+# Utility Helpers
+
+These small helper functions streamline common setup tasks.
+
+## `initialize_exp`
+
+Initialize the PsychoPy window and keyboard while setting up logging.
+
+```python
+from psyflow import initialize_exp, TaskSettings
+
+settings = TaskSettings.from_dict({"fullscreen": False})
+win, kb = initialize_exp(settings)
+```
+
+## `count_down`
+
+Display a simple countdown before the experiment starts.
+
+```python
+from psyflow import count_down
+
+count_down(win, seconds=3, color="white")
+```
+
+## `list_serial_ports`
+
+Quickly list available serial ports (alias of `show_ports`).
+
+```python
+from psyflow import list_serial_ports
+
+list_serial_ports()  # prints numbered ports to the console
+```
+
+## `list_supported_voices`
+
+Retrieve available voices for speech synthesis via `edge-tts`.
+
+```python
+from psyflow import list_supported_voices
+
+voices = list_supported_voices(filter_lang="en")
+print(voices[0]["ShortName"])  # Inspect voice attributes
+```
+
+Use `list_supported_voices(human_readable=True)` to print a formatted table.

psyflow/utils.py

@@ -21,6 +21,17 @@ def show_ports():
             print(f"[{i}] {p.device} - {p.description}")
 
 
+def list_serial_ports():
+    """Alias for :func:`show_ports`.
+
+    Returns
+    -------
+    None
+        This function simply calls :func:`show_ports` and prints the ports.
+    """
+    return show_ports()
+
+
 
 
 from cookiecutter.main import cookiecutter