docs: expand legacy cli and api pages

docs/source/legacy/cli-detect.md

@@ -1,38 +1,50 @@
-# Legacy CLI workflow: `batdetect2 detect`
+# CLI workflow: `batdetect2 detect`
 
 This page documents the previous CLI workflow based on `batdetect2 detect`.
 
 ```{warning}
-This is legacy documentation.
+This is documentation for a previous version of batdetect2.
 For new workflows, use `batdetect2 process directory` instead.
 If you are migrating, start with {doc}`migration-guide`.
 ```
 
-## Legacy command shape
+## Processing a folder of audio files
 
 ```bash
 batdetect2 detect AUDIO_DIR ANN_DIR DETECTION_THRESHOLD
 ```
 
-Common legacy options included:
+Example:
-
-- `--cnn_features`
-- `--spec_features`
-- `--time_expansion_factor`
-- `--save_preds_if_empty`
-- `--model_path`
-
-## Current replacement
-
-The closest current CLI entry point is:
 
 ```bash
-batdetect2 process directory \
+batdetect2 detect example_data/audio/ example_data/anns/ 0.3
-  path/to/model.ckpt \
-  path/to/audio_dir \
-  path/to/outputs
 ```
 
+This command scans a directory of audio files, runs the BatDetect2 detector on
+each file, and writes BatDetect2-style outputs into `ANN_DIR`.
+Those outputs usually include one JSON file and one CSV file per recording, and
+can optionally include extra feature CSVs.
+
+`AUDIO_DIR` is the folder containing the input `.wav` files.
+`ANN_DIR` is the folder where model outputs are written.
+
+`DETECTION_THRESHOLD` controls which detections are kept.
+Predictions below this score are discarded.
+Smaller values keep more detections, but usually also increase mistakes.
+
+Common options:
+
+- `--cnn_features` Write extra CNN feature CSV files for each recording.
+- `--spec_features` Extract and write traditional acoustic spectrogram feature
+  CSV files.
+  These are saved as `*_spec_features.csv` files.
+- `--time_expansion_factor` Set the time expansion factor used for all files in
+  the run.
+- `--save_preds_if_empty` Save output files even when no detections are found.
+- `--model_path` Use a specific checkpoint instead of the included default
+  model.
+  If omitted, the command uses the default model trained on UK data.
+
 ## Related pages
 
 - Migration guide:

docs/source/legacy/python-api.md

@@ -3,37 +3,52 @@
 This page documents the previous Python API workflow based on `batdetect2.api`.
 
 ```{warning}
-This is legacy documentation.
+This is documentation for a previous version of batdetect2.
-For new workflows, use `batdetect2.api_v2.BatDetect2API`.
+For new workflows, use `batdetect2.BatDetect2API`.
 If you are migrating, start with {doc}`migration-guide`.
 ```
 
-## Legacy entry points
+## Using BatDetect2 in Python
 
-Common legacy functions included:
+If you prefer to process data inside a Python script, you can use the `batdetect2.api` module.
 
-- `process_file`
+This interface gives you a simple entry point for running the built-in BatDetect2 model and also exposes the default model and default configuration more directly than the current API.
-- `process_audio`
-- `process_spectrogram`
-- `load_audio`
-- `generate_spectrogram`
-- `postprocess`
 
-The legacy API also exposed the default model and default config more directly.
+You can process a whole file in one step, or load audio, generate a spectrogram, and work with lower-level functions yourself.
 
-## Current replacement
+Common functions:
 
-The current Python path is:
+- `process_file` Load an audio file, run the model, and return BatDetect2-style results for that recording.
+- `process_audio` Run inference on an audio array that is already loaded in memory.
+- `process_spectrogram` Run inference starting from a spectrogram tensor instead of raw audio.
+- `load_audio` Load and resample audio using the legacy preprocessing path.
+- `generate_spectrogram` Convert audio into the spectrogram representation expected by the model.
+- `postprocess` Convert raw model outputs into detections and extracted features.
+
+Typical usage:
 
 ```python
-from pathlib import Path
+import batdetect2.api as api
 
-from batdetect2.api_v2 import BatDetect2API
+AUDIO_FILE = "example_data/audio/20170701_213954-MYOMYS-LR_0_0.5.wav"
 
-api = BatDetect2API.from_checkpoint(Path("path/to/model.ckpt"))
+# Process a whole file
-prediction = api.process_file(Path("path/to/audio.wav"))
+results = api.process_file(AUDIO_FILE)
+annotations = results["pred_dict"]["annotation"]
+
+# Or, load audio and compute spectrograms
+audio = api.load_audio(AUDIO_FILE)
+spec = api.generate_spectrogram(audio)
+
+# And process the audio or the spectrogram with the model
+detections, features, spec = api.process_audio(audio)
+detections, features = api.process_spectrogram(spec)
+
+# Integrate the detections or extracted features into your own analysis
 ```
 
+This interface is most useful when you want to work directly with detections, features, spectrograms, or intermediate arrays inside your own code.
+
 ## Related pages
 
 - Migration guide: {doc}`migration-guide`