From d460472717bc177651fd79acde0712c0259debc8 Mon Sep 17 00:00:00 2001
From: lochhh <changhuan.lo@ucl.ac.uk>
Date: Fri, 24 Nov 2023 15:49:24 +0000
Subject: [PATCH] Update docs on saving to SLEAP file

---
 docs/source/conf.py            |  2 +-
 docs/source/getting_started.md | 49 ++++++++++++++++++++++++----------
 2 files changed, 36 insertions(+), 15 deletions(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index a122cf07..8658e6e8 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -157,7 +157,7 @@
     "myst-parser": "https://myst-parser.readthedocs.io/en/latest/{{path}}#{{fragment}}",
     "napari": "https://napari.org/dev/{{path}}",
     "setuptools-scm": "https://setuptools-scm.readthedocs.io/en/latest/{{path}}#{{fragment}}",
-    "sleap": "https://sleap.ai/",
+    "sleap": "https://sleap.ai/{{path}}#{{fragment}}",
     "sphinx-gallery": "https://sphinx-gallery.github.io/stable/{{path}}",
     "xarray": "https://docs.xarray.dev/en/stable/{{path}}#{{fragment}}",
 }
diff --git a/docs/source/getting_started.md b/docs/source/getting_started.md
index 6c348e65..ff2d0375 100644
--- a/docs/source/getting_started.md
+++ b/docs/source/getting_started.md
@@ -206,29 +206,50 @@ to visualise the data. Check out the [Load and explore pose tracks](./examples/l
 example for inspiration.
 
 ## Saving data
-You can save movement datasets to disk in a variety of formats.
-This includes saving to DeepLabCut-style files (.h5 or .csv) and
-SLEAP-style analysis files (.h5). When saving to SLEAP-style files,
-do note that only `track_names`, `node_names`, `tracks`, `track_occupancy`,
-`point_scores`, and `labels_path` are saved. Other attributes and data variables
-(i.e., `instance_scores`, `tracking_scores`, `edge_names`, `edge_inds`, `video_path`,
-`video_ind`, and `provenance`) are not currently supported. To learn more about what
-each attribute and data variable represents, see the [SLEAP documentation](sleap:api/sleap.info.write_tracking_h5.html#module-sleap.info.write_tracking_h5).
+You can save movement datasets to disk in a variety of formats, including
+DeepLabCut-style files (.h5 or .csv) and [SLEAP-style analysis files](sleap:tutorials/analysis) (.h5).
+
+First import the `movement.io.save_poses` module:
 
 ```python
 from movement.io import save_poses
+```
 
-# save to DeepLabCut-style file
-save_poses.to_dlc_file(ds, "/path/to/file.h5")  # preferred format for DeepLabCut
-save_poses.to_dlc_file(ds, "/path/to/file.csv")
+Then, use the `to_dlc_file` or `to_sleap_analysis_file` functions to save the data.
 
-# save to SLEAP-style file
+:::::{tab-set}
+
+::::{tab-item} SLEAP
+
+Save to SLEAP analysis files (`.h5`):
+```python
 save_poses.to_sleap_analysis_file(ds, "/path/to/file.h5")
 ```
 
-Instead of saving to file directly, you can also convert the dataset to a
-DeepLabCut-style `pandas.DataFrame` first:
+:::{note}
+When saving to SLEAP-style files, only `track_names`, `node_names`, `tracks`, `track_occupancy`,
+`point_scores`, and `labels_path` are saved. Other attributes and data variables
+(i.e., `instance_scores`, `tracking_scores`, `edge_names`, `edge_inds`, `video_path`,
+`video_ind`, and `provenance`) are not currently supported. To learn more about what
+each attribute and data variable represents, see the
+[SLEAP documentation](sleap:api/sleap.info.write_tracking_h5.html#module-sleap.info.write_tracking_h5).
+:::
+::::
+
+::::{tab-item} DeepLabCut
+
+Save to DeepLabCut-style files (`.h5` or `.csv`):
+```python
+save_poses.to_dlc_file(ds, "/path/to/file.h5")  # preferred format
+save_poses.to_dlc_file(ds, "/path/to/file.csv")
+```
+
+Alternatively, you can first convert the dataset to a
+DeepLabCut-style `pandas.DataFrame` using the `to_dlc_df` function:
 ```python
 df = save_poses.to_dlc_df(ds)
 ```
 and then save it to file using any `pandas` method, e.g. `to_hdf` or `to_csv`.
+::::
+
+:::::