Revamp quick-start guides and update TOC

C-Achard · C-Achard · commit 01f907e465c4 · 2026-06-01T11:10:35.000+02:00
Add single- and multi-animal quick-start pages to the Main workflows overview in _toc.yml and substantially rewrite both quick-start docs. single_animal_quick_guide.md was reorganized into a clear step-by-step workflow (create project, configure, extract/label frames, create dataset, train/evaluate, analyze/filter/plot/create videos) with concrete Python examples, notes, and tips (use absolute paths, no spaces in body-part names). tutorial_maDLC.md was refactored into a multi-animal overview with GUI and Python workflows, clearer config guidance for multi-animal fields, extraction/annotation/checking steps, separate training engine examples (PyTorch/TensorFlow), and explicit tracking steps (analyze, convert detections, stitch tracklets, create labeled videos) plus helpful notes. Overall improvements focus on clarity, concrete examples, and actionable tips for users.
diff --git a/_toc.yml b/_toc.yml
@@ -11,13 +11,14 @@ parts:
           - file: docs/docker
       # - file: docs/quick-start/index
         # sections:
-          # - file: docs/quick-start/single_animal_quick_guide
-          # - file: docs/quick-start/tutorial_maDLC
 
   - caption: Main workflows overview
     chapters:
       - file: docs/main-workflows/user-guide
-      - file: docs/main-workflows/multi-animal-tracking
+        sections:
+          - file: docs/quick-start/single_animal_quick_guide
+          - file: docs/quick-start/tutorial_maDLC
+          - file: docs/main-workflows/multi-animal-tracking
       # - file: docs/standardDeepLabCut_UserGuide
       # - file: docs/maDLC_UserGuide
       - file: docs/Overviewof3D
diff --git a/docs/main-workflows/multi-animal-tracking.md b/docs/main-workflows/multi-animal-tracking.md
@@ -227,6 +227,3 @@ align: center
 ---
 Short demo of the tracklet refinement workflow.
 ```
-
-```
-```
diff --git a/docs/quick-start/single_animal_quick_guide.md b/docs/quick-start/single_animal_quick_guide.md
@@ -11,90 +11,149 @@ deeplabcut:
 
 (file:single-animal-quick-start)=
 
-# QUICK GUIDE to single Animal Training:
+# Single-animal at a glance
 
-**The main steps to take you from project creation to analyzed videos:**
+This page summarizes the main DeepLabCut functions used in a standard single-animal
+2D pose-estimation workflow, from project creation to analyzed videos.
 
-Open ipython in the terminal:
+## Start Python
 
-```
+Open a terminal and start an interactive Python session, for example with IPython:
+
+```bash
 ipython
 ```
 
-Import DeepLabCut:
+Then import DeepLabCut:
 
-```
+```python
 import deeplabcut
 ```
 
-Create a new project:
+## Workflow
 
-```
-deeplabcut.create_new_project("project_name", "experimenter", ["path of video 1", "path of video2", ..])
-```
+### 1. Create a project
 
-Set a config_path variable for ease of use + go edit this file!:
+```python
+project_name = "project_name"
+experimenter = "experimenter"
+video_paths = [
+    "/absolute/path/to/video_1.mp4",
+    "/absolute/path/to/video_2.mp4",
+]
 
+config_path = deeplabcut.create_new_project(
+    project_name,
+    experimenter,
+    video_paths,
+    copy_videos=True,
+)
 ```
-config_path = "yourdirectory/project_name/config.yaml"
+
+```{note}
+Use absolute paths to your video files. The returned `config_path` is the full path to
+the project `config.yaml` file and is used throughout the rest of the workflow.
 ```
 
-Extract frames:
+### 2. Configure the project
 
+Open the generated `config.yaml` file and edit it for your experiment.
+
+At this stage, define the body parts or points of interest that you want to track. You
+can also adjust project settings such as the number of frames to extract, visualization
+settings, and training options.
+
+```{important}
+Do not include spaces in body-part names.
 ```
+
+### 3. Extract frames
+
+```python
 deeplabcut.extract_frames(config_path)
 ```
 
-Label frames:
+### 4. Label frames
 
-```
+```python
 deeplabcut.label_frames(config_path)
 ```
 
-Check labels \[OPTIONAL\]:
+### 5. Check labels
 
-```
+```python
 deeplabcut.check_labels(config_path)
 ```
 
-Create training dataset:
-
+```{tip}
+This step is optional, but strongly recommended. Use the generated labeled images to
+visually confirm that the annotations were saved correctly before training.
 ```
+
+### 6. Create the training dataset
+
+```python
 deeplabcut.create_training_dataset(config_path)
 ```
 
-Train the network:
+### 7. Train the network
 
-```
+```python
 deeplabcut.train_network(config_path)
 ```
 
-Evaluate the trained network:
+### 8. Evaluate the trained network
 
-```
+```python
 deeplabcut.evaluate_network(config_path)
 ```
 
-Video analysis:
+Inspect the evaluation results before moving on to video analysis. If pose-estimation
+quality is not sufficient, improve the labels, add more training data, or train for
+longer before continuing.
 
-```
-deeplabcut.analyze_videos(config_path, ["path of video 1", "path of video2", ..])
+### 9. Analyze videos
+
+```python
+deeplabcut.analyze_videos(
+    config_path,
+    video_paths,
+)
 ```
 
-Filter predictions \[OPTIONAL\]:
+### 10. Filter predictions
 
+```python
+deeplabcut.filterpredictions(
+    config_path,
+    video_paths,
+)
 ```
-deeplabcut.filterpredictions(config_path, ["path of video 1", "path of video2", ..])
+
+```{note}
+Filtering is optional. It can help smooth pose predictions before plotting
+trajectories or creating labeled videos.
 ```
 
-Plot results (trajectories):
+### 11. Plot trajectories
 
-```
-deeplabcut.plot_trajectories(config_path, ["path of video 1", "path of video2", ..], filtered=True)
+```python
+deeplabcut.plot_trajectories(
+    config_path,
+    video_paths,
+    filtered=True,
+)
 ```
 
-Create a video:
+### 12. Create labeled videos
 
+```python
+deeplabcut.create_labeled_video(
+    config_path,
+    video_paths,
+    filtered=True,
+)
 ```
-deeplabcut.create_labeled_video(config_path, ["path of video 1", "path of video2", ..], filtered=True)
-```
+
+This creates videos with the predicted keypoints overlaid, which is useful for a quick
+visual inspection of tracking quality.
diff --git a/docs/quick-start/tutorial_maDLC.md b/docs/quick-start/tutorial_maDLC.md

-Original file line number
+Diff line change
 ---
 Short demo of the tracklet refinement workflow.
 ```
+-
 -```
 -```