diff --git a/docs/requirements.txt b/docs/requirements.txt
index 0a950f2e..6d4f2cf3 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -8,5 +8,6 @@ sphinx
sphinx-autodoc-typehints
sphinx-design
sphinx-gallery
+sphinx-notfound-page
sphinx-sitemap
tables
diff --git a/docs/source/_templates/api_index_head.rst b/docs/source/_templates/api_index_head.rst
index 0c1e6b7e..325f9f0a 100644
--- a/docs/source/_templates/api_index_head.rst
+++ b/docs/source/_templates/api_index_head.rst
@@ -3,7 +3,7 @@
.. _target-api:
-API Reference
+API reference
=============
Information on specific functions, classes, and methods.
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 42ac0668..5d8414df 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -44,6 +44,7 @@
"sphinx.ext.intersphinx",
"myst_parser",
"nbsphinx",
+ "notfound.extension",
"sphinx_design",
"sphinx_gallery.gen_gallery",
"sphinx_sitemap",
@@ -114,6 +115,7 @@
# do not render config params set as # sphinx_gallery_config [= value]
}
+
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = "pydata_sphinx_theme"
@@ -205,3 +207,22 @@
"xarray": ("https://docs.xarray.dev/en/stable/", None),
"scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),
}
+
+
+# What to show on the 404 page
+notfound_context = {
+ "title": "Page Not Found",
+ "body": """
+Page Not Found
+
+Sorry, we couldn't find that page.
+
+We occasionally restructure the movement website, and some links may have broken.
+
+Try using the search box or go to the homepage.
+""",
+}
+
+# needed for GH pages (vs readthedocs),
+# because we have no '///' in the URL
+notfound_urls_prefix = None
diff --git a/docs/source/getting_started/index.md b/docs/source/getting_started/index.md
deleted file mode 100644
index 4795a9cd..00000000
--- a/docs/source/getting_started/index.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Getting Started
-
-Start by [installing the package](installation.md).
-
-After that, try [loading some of your own tracked poses](target-loading-pose-tracks) or [bounding boxes' trajectories](target-loading-bbox-tracks),
-from one of the [supported formats](target-formats).
-Alternatively, you can use the [sample data](target-sample-data)
-provided with the package.
-
-Once you have loaded some data, feel free to explore the structure and
-usage of [movement datasets](movement_dataset.md), which are a central
-concept in the package.
-
-```{toctree}
-:maxdepth: 2
-:caption: Contents
-
-installation
-input_output
-sample_data
-movement_dataset
-```
diff --git a/docs/source/getting_started/sample_data.md b/docs/source/getting_started/sample_data.md
deleted file mode 100644
index 5d3a4f99..00000000
--- a/docs/source/getting_started/sample_data.md
+++ /dev/null
@@ -1,54 +0,0 @@
-(target-sample-data)=
-# Sample data
-
-`movement` includes some sample data files that you can use to
-try the package out. These files contain pose and bounding boxes' tracks from
-various [supported formats](target-supported-formats).
-
-You can list the available sample data files using:
-
-```python
-from movement import sample_data
-
-file_names = sample_data.list_datasets()
-print(*file_names, sep='\n') # print each sample file in a separate line
-```
-
-Each sample file is prefixed with the name of the software package
-that was used to generate it.
-
-To load one of the sample files as a
-[movement dataset](target-poses-and-bboxes-dataset), use the
-{func}`movement.sample_data.fetch_dataset()` function:
-
-```python
-filename = "SLEAP_three-mice_Aeon_proofread.analysis.h5"
-ds = sample_data.fetch_dataset(filename)
-```
-Some sample datasets also have an associated video file
-(the video for which the data was predicted). You can request
-to download the sample video by setting `with_video=True`:
-
-```python
-ds = sample_data.fetch_dataset(filename, with_video=True)
-```
-
-If available, the video file is downloaded and its path is stored
-in the `video_path` attribute of the dataset (i.e., `ds.video_path`).
-The value of this attribute is `None` if no video file is
-available for this dataset, or if you did not request it.
-
-Some datasets also include a sample frame file, which is a single
-still frame extracted from the video. This can be useful for visualisation
-(e.g., as a background image for plotting trajectories). If available,
-this file is always downloaded when fetching the dataset,
-and its path is stored in the `frame_path` attribute
-(i.e., `ds.frame_path`). If no frame file is available for the dataset,
- `ds.frame_path=None`.
-
-:::{dropdown} Under the hood
-:color: info
-:icon: info
-When you import the `sample_data` module with `from movement import sample_data`,
-`movement` downloads a small metadata file to your local machine with information about the latest sample datasets available. Then, the first time you call the `fetch_dataset()` function, `movement` downloads the requested file to your machine and caches it in the `~/.movement/data` directory. On subsequent calls, the data are directly loaded from this local cache.
-:::
diff --git a/docs/source/index.md b/docs/source/index.md
index 1b7382cc..43aba6df 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -6,11 +6,11 @@ A Python toolbox for analysing animal body movements across space and time.
::::{grid} 1 2 2 3
:gutter: 3
-:::{grid-item-card} {fas}`rocket;sd-text-primary` Getting Started
-:link: getting_started/index
+:::{grid-item-card} {fas}`book;sd-text-primary` User guide
+:link: user_guide/index
:link-type: doc
-Installation, first steps and key concepts.
+Installation, supported formats and key concepts.
:::
:::{grid-item-card} {fas}`chalkboard-user;sd-text-primary` Examples
@@ -60,7 +60,7 @@ Find out more on our [mission and scope](target-mission) statement and our [road
:maxdepth: 2
:hidden:
-getting_started/index
+user_guide/index
examples/index
community/index
api_index
diff --git a/docs/source/user_guide/index.md b/docs/source/user_guide/index.md
new file mode 100644
index 00000000..e8caa8cf
--- /dev/null
+++ b/docs/source/user_guide/index.md
@@ -0,0 +1,45 @@
+# User guide
+
+Start by [installing the package](installation.md) and
+[loading your own tracking data](input_output.md), or playing with some
+[sample data](target-sample-data) provided with the package.
+
+Before you dive deeper, we highly recommend reading about the structure
+and usage of [movement datasets](movement_dataset.md), which are a central
+concept in the package.
+
+::::{grid} 1 2 2 3
+:gutter: 3
+
+:::{grid-item-card} {fas}`wrench;sd-text-primary` Installation
+:link: installation
+:link-type: doc
+
+Install the package with `conda` or `pip`.
+:::
+
+:::{grid-item-card} {fas}`download;sd-text-primary` Input/Output
+:link: input_output
+:link-type: doc
+
+Load and save tracking data.
+:::
+
+:::{grid-item-card} {fas}`table;sd-text-primary` The movement datasets
+:link: movement_dataset
+:link-type: doc
+
+Learn about our data structures.
+:::
+
+::::
+
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+installation
+input_output
+movement_dataset
+```
diff --git a/docs/source/getting_started/input_output.md b/docs/source/user_guide/input_output.md
similarity index 80%
rename from docs/source/getting_started/input_output.md
rename to docs/source/user_guide/input_output.md
index ccb16a7b..6cc1f2a4 100644
--- a/docs/source/getting_started/input_output.md
+++ b/docs/source/user_guide/input_output.md
@@ -257,3 +257,59 @@ with open(filepath, mode="w", newline="") as file:
```
Alternatively, we can convert the `movement` bounding boxes' dataset to a pandas DataFrame with the {func}`.xarray.DataArray.to_dataframe()` method, wrangle the dataframe as required, and then apply the {func}`.pandas.DataFrame.to_csv()` method to save the data as a .csv file.
+
+
+(target-sample-data)=
+## Sample data
+
+`movement` includes some sample data files that you can use to
+try the package out. These files contain pose and bounding boxes' tracks from
+various [supported formats](target-supported-formats).
+
+You can list the available sample data files using:
+
+```python
+from movement import sample_data
+
+file_names = sample_data.list_datasets()
+print(*file_names, sep='\n') # print each sample file in a separate line
+```
+
+Each sample file is prefixed with the name of the software package
+that was used to generate it.
+
+To load one of the sample files as a
+[movement dataset](target-poses-and-bboxes-dataset), use the
+{func}`movement.sample_data.fetch_dataset()` function:
+
+```python
+filename = "SLEAP_three-mice_Aeon_proofread.analysis.h5"
+ds = sample_data.fetch_dataset(filename)
+```
+Some sample datasets also have an associated video file
+(the video for which the data was predicted). You can request
+to download the sample video by setting `with_video=True`:
+
+```python
+ds = sample_data.fetch_dataset(filename, with_video=True)
+```
+
+If available, the video file is downloaded and its path is stored
+in the `video_path` attribute of the dataset (i.e., `ds.video_path`).
+The value of this attribute is `None` if no video file is
+available for this dataset, or if you did not request it.
+
+Some datasets also include a sample frame file, which is a single
+still frame extracted from the video. This can be useful for visualisation
+(e.g., as a background image for plotting trajectories). If available,
+this file is always downloaded when fetching the dataset,
+and its path is stored in the `frame_path` attribute
+(i.e., `ds.frame_path`). If no frame file is available for the dataset,
+ `ds.frame_path=None`.
+
+:::{dropdown} Under the hood
+:color: info
+:icon: info
+When you import the `sample_data` module with `from movement import sample_data`,
+`movement` downloads a small metadata file to your local machine with information about the latest sample datasets available. Then, the first time you call the `fetch_dataset()` function, `movement` downloads the requested file to your machine and caches it in the `~/.movement/data` directory. On subsequent calls, the data are directly loaded from this local cache.
+:::
diff --git a/docs/source/getting_started/installation.md b/docs/source/user_guide/installation.md
similarity index 100%
rename from docs/source/getting_started/installation.md
rename to docs/source/user_guide/installation.md
diff --git a/docs/source/getting_started/movement_dataset.md b/docs/source/user_guide/movement_dataset.md
similarity index 100%
rename from docs/source/getting_started/movement_dataset.md
rename to docs/source/user_guide/movement_dataset.md