docs: polish docs entry points and metadata

docs/source/getting_started.md

@@ -1,52 +1,38 @@
 # Getting started
 
-If you want to run BatDetect2 on your recordings, start with the command-line
+BatDetect2 can be used in two ways: through the `batdetect2` command line interface (CLI), or as the `batdetect2` Python package.
-route below.
+The CLI route does not require coding.
+You run commands in the terminal and, in some cases, write configuration files.
+The Python route gives you more flexibility and lets you integrate the model into your own workflows or experiments.
+For most common use cases, both routes give you the same results.
 
-You do not need to write Python code for a standard first run.
+## Try it out
-
-BatDetect2 also has a Python interface, but that is mainly for users writing
-their own analysis scripts.
-
-- Use the command-line route if you want to run an existing model or train your
-  own model by typing commands in a terminal window.
-- Use the Python route only if you already want to work in scripts or notebooks.
-
-```{note}
-If you are looking for the previous BatDetect2 workflow based on `batdetect2 detect` or `batdetect2.api`, go to {doc}`legacy/index`.
-New docs default to the current `process` CLI and `BatDetect2API` workflow.
-```
 
 If you want to try BatDetect2 before installing anything locally:
 
 - [Hugging Face demo (UK species)](https://huggingface.co/spaces/macaodha/batdetect2)
 - [Google Colab notebook](https://colab.research.google.com/github/macaodha/batdetect2/blob/master/batdetect2_notebook.ipynb)
 
-## The simplest route for most users
+## Installation
 
-1. Install BatDetect2.
+To use `batdetect2` on your machine, you need to install it first.
-2. Use a model checkpoint.
+We recommend using `uv` for that.
-3. Run the first tutorial on a folder of recordings.
+`uv` is a tool that helps manage Python software cleanly, without mixing it into the rest of your machine.
+Install `uv` first by following the [installation instructions](https://docs.astral.sh/uv/getting-started/installation/).
 
-If that is what you want, you can ignore the Python sections for now.
+### One-off usage
 
-## Install BatDetect2
+If you are not ready to install `batdetect2` permanently, you can try it with:
 
-We recommend `uv` for both workflows.
+```bash
+uvx batdetect2
+```
 
-`uv` is a tool that helps install Python software cleanly, without mixing it
+This still downloads the code and dependencies and runs them on your machine, but the environment is temporary.
-into the rest of your machine.
 
-- Use `uv tool` to install the CLI.
+### Install the CLI
-- Use `uv add` to add `batdetect2` as a dependency in a Python project.
 
-Install `uv` first by following their
+If you want the `batdetect2` CLI to always be available in your terminal, run:
-[installation instructions](https://docs.astral.sh/uv/getting-started/installation/).
-
-## Install the CLI
-
-The following installs `batdetect2` in its own small environment and makes the
-`batdetect2` command available on your machine.
 
 ```bash
 uv tool install batdetect2
@@ -61,65 +47,45 @@ uv tool upgrade batdetect2
 Verify the CLI is available:
 
 ```bash
-batdetect2 --help
+batdetect2
 ```
 
-Run your first workflow:
+You can then run your first workflow.
+See {doc}`tutorials/run-inference-on-folder` for more details.
 
-Go to {doc}`tutorials/run-inference-on-folder` for a complete first run.
+### Add it to your Python project
 
-## Choose a model checkpoint
+If you are using BatDetect2 from Python code and already manage your projects with `uv`, you can add it with:
-
-The current command-line and Python workflows expect an explicit checkpoint
-path.
-
-A checkpoint is the saved model file that BatDetect2 will use for prediction.
-
-You can use:
-
-- a checkpoint you trained yourself, or
-- a checkpoint distributed with your installation or repository checkout.
-
-In this repository checkout, an example pretrained checkpoint is available at:
-
-```text
-src/batdetect2/models/checkpoints/Net2DFast_UK_same.pth.tar
-```
-
-Use that path in the tutorial commands if you want a concrete starting point
-from this source tree.
-
-## Python route for users writing code
-
-If you are using BatDetect2 from Python code, add it to your Python project:
 
 ```bash
 uv add batdetect2
 ```
 
-This keeps your project settings and installed packages in sync.
+If you want to upgrade it later:
 
-### Alternative with `pip`
+```bash
+uv add -U batdetect2
+```
 
-If you prefer `pip`, create and activate a virtual environment first:
+#### Alternative with `pip`
+
+If you prefer `pip`, you can use:
+
+```bash
+pip install batdetect2
+```
+
+It is a good idea to create a separate virtual environment first so this does not interfere with other Python environments.
 
 ```bash
 python -m venv .venv
 source .venv/bin/activate
 ```
 
-Then install from PyPI:
-
-```bash
-pip install batdetect2
-```
-
 ## What's next
 
-- Run your first workflow on a folder of recordings:
+- Run your first workflow on a folder of recordings: {doc}`tutorials/run-inference-on-folder`
-  {doc}`tutorials/run-inference-on-folder`
+- If you write code and want the Python route: {doc}`tutorials/integrate-with-a-python-pipeline`
-- If you write code and want the Python route:
-  {doc}`tutorials/integrate-with-a-python-pipeline`
 - For common practical tasks, go to {doc}`how_to/index`
 - For detailed command help, go to {doc}`reference/cli/index`
-- To understand outputs and trade-offs, go to {doc}`explanation/index`
+- To understand the model and its outputs, go to {doc}`explanation/index`

docs/source/index.md

@@ -4,50 +4,42 @@ Welcome to the BatDetect2 documentation.
 
 ## What is BatDetect2?
 
-`batdetect2` detects bat echolocation calls in audio recordings.
+`batdetect2` is a deep learning model and software package for detecting and
+classifying bat echolocation calls in high-frequency audio recordings.
 
-It can help you screen large collections of recordings, find files that need
+You can use it from the command line or from Python, depending on how much
-expert review, and support ecology and conservation work where manual review
+control you need.
-alone would be slow.
 
-In practice, BatDetect2 takes recordings, looks for likely bat calls, draws a
+In practice, BatDetect2 scans a recording, finds sounds that look like bat
-box around each detected event, and scores the most likely class for that event.
+calls, and returns one result for each detected call.
+Each result can include where the call appears in the recording, shown as a box
+with start and end time and the lowest and highest frequency, how confident the
+model is that it found a call, and how strongly it matches the available
+classes.
 
-The current default model is trained for 17 UK species.
+The built-in default model is trained for 17 UK species.
+The package also supports custom training, fine-tuning, evaluation, and more
+advanced workflows from Python.
 
-The library also supports custom training, fine-tuning, evaluation, and more
+For more detail on the underlying approach, see the pre-print:
-advanced use from Python.
-
-For details on the underlying approach, see the pre-print:
 [Towards a General Approach for Bat Echolocation Detection and Classification](https://www.biorxiv.org/content/10.1101/2022.12.14.520490v1)
 
-## A good first use for BatDetect2
-
-BatDetect2 is a good fit when you want to:
-
-- scan many recordings for likely bat activity,
-- prioritize files for expert review,
-- compare outputs across projects with appropriate caution,
-- build reviewed local datasets for later model improvement.
-
-It is not a substitute for validation.
-
-## Main user journeys
-
-- I want to run the model on my recordings:
-  {doc}`tutorials/run-inference-on-folder`
-- I write code and want to use Python:
-  {doc}`tutorials/integrate-with-a-python-pipeline`
-- I want to train or fine-tune a custom model:
-  {doc}`tutorials/train-a-custom-model`
-- I want to evaluate a trained model on held-out data:
-  {doc}`tutorials/evaluate-on-a-test-set`
-
 ```{warning}
 Treat outputs as model predictions, not ground truth.
 Always validate on reviewed local data before using results for ecological inference.
 ```
 
+## What can I do with it?
+
+- I want to run the model on my recordings:
+  {doc}`tutorials/run-inference-on-folder`
+- I write code and want to use it from Python:
+  {doc}`tutorials/integrate-with-a-python-pipeline`
+- I want to train or fine-tune a custom model:
+  {doc}`tutorials/train-a-custom-model`
+- I want to evaluate a trained model on held-out data:
+  {doc}`tutorials/evaluate-on-a-test-set`
+
 ```{note}
 Looking for the previous BatDetect2 workflow?
 See {doc}`legacy/index`.

pyproject.toml

@@ -37,10 +37,10 @@ classifiers = [
   "Intended Audience :: Science/Research",
   "Natural Language :: English",
   "Operating System :: OS Independent",
-  "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
   "Topic :: Scientific/Engineering :: Artificial Intelligence",
   "Topic :: Software Development :: Libraries :: Python Modules",
   "Topic :: Multimedia :: Sound/Audio :: Analysis",