Create basic tutorial files, WIP

docs/source/index.md

@@ -21,11 +21,11 @@ For details on the approach please read our pre-print:
   analysis:
   {doc}`tutorials/run-inference-on-folder`
 - Train a custom model on your own annotated data:
-  {doc}`reference/cli/train`
+  {doc}`tutorials/train-a-custom-model`
 - Evaluate model performance on a held-out test set:
-  {doc}`reference/cli/evaluate`
+  {doc}`tutorials/evaluate-on-a-test-set`
 - Integrate batdetect2 into Python scripts and notebooks:
-  {doc}`reference/index`
+  {doc}`tutorials/integrate-with-a-python-pipeline`
 
 ```{warning}
 Treat outputs as model predictions, not ground truth.

docs/source/tutorials/evaluate-on-a-test-set.md

@@ -0,0 +1,35 @@
+# Tutorial: Evaluate on a test set
+
+This tutorial shows how to evaluate a trained checkpoint on a held-out dataset
+and inspect the output metrics.
+
+## Before you start
+
+- A trained model checkpoint.
+- A test dataset config file.
+- (Optional) Targets, audio, inference, and evaluation config overrides.
+
+## Tutorial steps
+
+1. Select a checkpoint and a test dataset.
+2. Run `batdetect2 evaluate`.
+3. Inspect output metrics and prediction artifacts.
+4. Record evaluation settings for reproducibility.
+
+## Example command
+
+```bash
+batdetect2 evaluate \
+  path/to/model.ckpt \
+  path/to/test_dataset.yaml \
+  --output-dir path/to/eval_outputs
+```
+
+## What to do next
+
+- Compare thresholds on representative files:
+  {doc}`../how_to/tune-detection-threshold`
+- Check full evaluate options: {doc}`../reference/cli/evaluate`
+
+This page is a starter scaffold and will be expanded with a full worked
+example.

docs/source/tutorials/index.md

@@ -3,13 +3,11 @@
 Tutorials are for learning by doing. They provide a single, reproducible path
 to a concrete outcome.
 
-## Who this section is for
-
-- Ecologists who want practical workflows with minimal coding.
-- New users who want to build confidence before customization.
-
 ```{toctree}
 :maxdepth: 1
 
 run-inference-on-folder
+train-a-custom-model
+evaluate-on-a-test-set
+integrate-with-a-python-pipeline
 ```

docs/source/tutorials/integrate-with-a-python-pipeline.md

@@ -0,0 +1,42 @@
+# Tutorial: Integrate with a Python pipeline
+
+This tutorial shows a minimal Python workflow for loading audio, running
+batdetect2, and collecting detections for downstream analysis.
+
+## Before you start
+
+- BatDetect2 installed in your Python environment.
+- A model checkpoint.
+- At least one input audio file.
+
+## Tutorial steps
+
+1. Load BatDetect2 in Python.
+2. Create an API instance from a checkpoint.
+3. Run `process_file` on one audio file.
+4. Read detection fields and class scores.
+5. Save or pass detections to your downstream pipeline.
+
+## Example code
+
+```python
+from pathlib import Path
+
+from batdetect2.api_v2 import BatDetect2API
+
+api = BatDetect2API.from_checkpoint(Path("path/to/model.ckpt"))
+prediction = api.process_file(Path("path/to/audio.wav"))
+
+for detection in prediction.detections:
+    top_class = api.get_top_class_name(detection)
+    score = detection.detection_score
+    print(top_class, score)
+```
+
+## What to do next
+
+- See API/config references: {doc}`../reference/index`
+- Learn practical CLI alternatives: {doc}`run-inference-on-folder`
+
+This page is a starter scaffold and will be expanded with a full worked
+example.

docs/source/tutorials/run-inference-on-folder.md

@@ -1,12 +1,14 @@
 # Tutorial: Run inference on a folder of audio files
 
-## Prerequisites
+This tutorial walks through a first end-to-end inference run with the CLI.
+
+## Before you start
 
 - BatDetect2 installed in your environment.
 - A folder containing `.wav` files.
 - A model checkpoint path.
 
-## Steps
+## Tutorial steps
 
 1. Choose your input and output directories.
 2. Run prediction with the CLI.
@@ -27,5 +29,5 @@ batdetect2 predict directory \
 - Use {doc}`../how_to/tune-detection-threshold` to tune sensitivity.
 - Use {doc}`../reference/cli/index` for full command options.
 
-Note: this is the initial Phase 1 scaffold and will be expanded with a full,
-validated end-to-end walkthrough.
+This page is a starter scaffold and will be expanded with a full worked
+example.

docs/source/tutorials/train-a-custom-model.md

@@ -0,0 +1,37 @@
+# Tutorial: Train a custom model
+
+This tutorial walks through a first custom training run using your own
+annotations.
+
+## Before you start
+
+- BatDetect2 installed.
+- A training dataset config file.
+- (Optional) A validation dataset config file.
+
+## Tutorial steps
+
+1. Prepare training and validation dataset config files.
+2. Choose target definitions and model/training config files.
+3. Run `batdetect2 train`.
+4. Check that checkpoints and logs are written.
+5. Run a quick sanity inference on a small audio subset.
+
+## Example command
+
+```bash
+batdetect2 train \
+  path/to/train_dataset.yaml \
+  --val-dataset path/to/val_dataset.yaml \
+  --targets path/to/targets.yaml \
+  --model-config path/to/model.yaml \
+  --training-config path/to/training.yaml
+```
+
+## What to do next
+
+- Evaluate the trained checkpoint: {doc}`evaluate-on-a-test-set`
+- Check full train options: {doc}`../reference/cli/train`
+
+This page is a starter scaffold and will be expanded with a full worked
+example.