From 4680b813b0f4041d6e1ea648746f13e68c4dabf2 Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Wed, 27 Nov 2024 11:21:30 +0000
Subject: [PATCH 01/10] renamed "Getting Started" to "User Guide"

---
 docs/source/index.md                                      | 8 ++++----
 docs/source/{getting_started => user_guide}/index.md      | 2 +-
 .../{getting_started => user_guide}/input_output.md       | 0
 .../{getting_started => user_guide}/installation.md       | 0
 .../{getting_started => user_guide}/movement_dataset.md   | 0
 .../source/{getting_started => user_guide}/sample_data.md | 0
 6 files changed, 5 insertions(+), 5 deletions(-)
 rename docs/source/{getting_started => user_guide}/index.md (97%)
 rename docs/source/{getting_started => user_guide}/input_output.md (100%)
 rename docs/source/{getting_started => user_guide}/installation.md (100%)
 rename docs/source/{getting_started => user_guide}/movement_dataset.md (100%)
 rename docs/source/{getting_started => user_guide}/sample_data.md (100%)

diff --git a/docs/source/index.md b/docs/source/index.md
index 1b7382cc..bb1c29af 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}`rocket;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/getting_started/index.md b/docs/source/user_guide/index.md
similarity index 97%
rename from docs/source/getting_started/index.md
rename to docs/source/user_guide/index.md
index 4795a9cd..e1c875f2 100644
--- a/docs/source/getting_started/index.md
+++ b/docs/source/user_guide/index.md
@@ -1,4 +1,4 @@
-# Getting Started
+# User Guide
 
 Start by [installing the package](installation.md).
 
diff --git a/docs/source/getting_started/input_output.md b/docs/source/user_guide/input_output.md
similarity index 100%
rename from docs/source/getting_started/input_output.md
rename to docs/source/user_guide/input_output.md
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
diff --git a/docs/source/getting_started/sample_data.md b/docs/source/user_guide/sample_data.md
similarity index 100%
rename from docs/source/getting_started/sample_data.md
rename to docs/source/user_guide/sample_data.md

From f6e5008ffde612aa9ba46dfe38f8fdbbc88ef742 Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Wed, 27 Nov 2024 18:17:40 +0000
Subject: [PATCH 02/10] setup redirects from old to new pages

---
 docs/requirements.txt |  1 +
 docs/source/conf.py   | 13 +++++++++++++
 2 files changed, 14 insertions(+)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 0a950f2e..0cc06524 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -8,5 +8,6 @@ sphinx
 sphinx-autodoc-typehints
 sphinx-design
 sphinx-gallery
+sphinx-reredirects
 sphinx-sitemap
 tables
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 42ac0668..23d1f93a 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -46,6 +46,7 @@
     "nbsphinx",
     "sphinx_design",
     "sphinx_gallery.gen_gallery",
+    "sphinx_reredirects",
     "sphinx_sitemap",
     "sphinx.ext.autosectionlabel",
 ]
@@ -114,6 +115,18 @@
     # do not render config params set as # sphinx_gallery_config [= value]
 }
 
+# Set up redirects for pages that were renamed or moved
+# using the sphinx-reredirects extension.
+# See: https://documatt.com/sphinx-reredirects/usage.html
+redirects = {
+    # from the old "getting_started" folder to the new "user_guide" folder
+    "getting_started/index": "../user_guide/index.html",
+    "getting_started/input_output": "../user_guide/input_output.html",
+    "getting_started/installation": "../user_guide/installation.html",
+    "getting_started/movement_dataset": "../user_guide/movement_dataset.html",
+    "getting_started/sample_data": "../user_guide/sample_data.html",
+}
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 html_theme = "pydata_sphinx_theme"

From 80c94e571e9b3b83e73540730ec818a009190e5c Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Wed, 27 Nov 2024 18:54:47 +0000
Subject: [PATCH 03/10] use cards in user guide

---
 docs/source/user_guide/index.md | 49 +++++++++++++++++++++++++++------
 1 file changed, 40 insertions(+), 9 deletions(-)

diff --git a/docs/source/user_guide/index.md b/docs/source/user_guide/index.md
index e1c875f2..baee6947 100644
--- a/docs/source/user_guide/index.md
+++ b/docs/source/user_guide/index.md
@@ -1,19 +1,50 @@
 # User Guide
 
-Start by [installing the package](installation.md).
+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.
 
-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
+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 4
+:gutter: 4
+
+:::{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` Sample data
+:link: sample_data
+:link-type: doc
+
+Play with some example datasets.
+:::
+
+:::{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
-:caption: Contents
+:hidden:
 
 installation
 input_output

From ef3c68fb913c7f589baf4a838984d51059b6a228 Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Wed, 27 Nov 2024 18:59:01 +0000
Subject: [PATCH 04/10] move sample_data section inside input/output

---
 docs/source/conf.py                    |  1 -
 docs/source/user_guide/index.md        | 11 +----
 docs/source/user_guide/input_output.md | 56 ++++++++++++++++++++++++++
 docs/source/user_guide/sample_data.md  | 54 -------------------------
 4 files changed, 58 insertions(+), 64 deletions(-)
 delete mode 100644 docs/source/user_guide/sample_data.md

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 23d1f93a..ecdeddef 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -124,7 +124,6 @@
     "getting_started/input_output": "../user_guide/input_output.html",
     "getting_started/installation": "../user_guide/installation.html",
     "getting_started/movement_dataset": "../user_guide/movement_dataset.html",
-    "getting_started/sample_data": "../user_guide/sample_data.html",
 }
 
 # -- Options for HTML output -------------------------------------------------
diff --git a/docs/source/user_guide/index.md b/docs/source/user_guide/index.md
index baee6947..43213658 100644
--- a/docs/source/user_guide/index.md
+++ b/docs/source/user_guide/index.md
@@ -8,8 +8,8 @@ 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 4
-:gutter: 4
+::::{grid} 1 2 2 3
+:gutter: 3
 
 :::{grid-item-card} {fas}`wrench;sd-text-primary` Installation
 :link: installation
@@ -25,13 +25,6 @@ Install the package with `conda` or `pip`.
 Load and save tracking data.
 :::
 
-:::{grid-item-card} {fas}`table;sd-text-primary` Sample data
-:link: sample_data
-:link-type: doc
-
-Play with some example datasets.
-:::
-
 :::{grid-item-card} {fas}`table;sd-text-primary` The movement datasets
 :link: movement_dataset
 :link-type: doc
diff --git a/docs/source/user_guide/input_output.md b/docs/source/user_guide/input_output.md
index ccb16a7b..6cc1f2a4 100644
--- a/docs/source/user_guide/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/user_guide/sample_data.md b/docs/source/user_guide/sample_data.md
deleted file mode 100644
index 5d3a4f99..00000000
--- a/docs/source/user_guide/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.
-:::

From 85b6d6188016e7c2838fd8e8e6df0c298f990c08 Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Wed, 27 Nov 2024 19:01:53 +0000
Subject: [PATCH 05/10] use the book icon for the user guide card

---
 docs/source/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/index.md b/docs/source/index.md
index bb1c29af..3763998e 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -6,7 +6,7 @@ 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` User Guide
+:::{grid-item-card} {fas}`book;sd-text-primary` User Guide
 :link: user_guide/index
 :link-type: doc
 

From fa5c8b9abe6b9c662c2556776be38d4cd40c000b Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Wed, 27 Nov 2024 19:30:00 +0000
Subject: [PATCH 06/10] removed sample_data doc from user_guide TOC

---
 docs/source/user_guide/index.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/source/user_guide/index.md b/docs/source/user_guide/index.md
index 43213658..f3222a5a 100644
--- a/docs/source/user_guide/index.md
+++ b/docs/source/user_guide/index.md
@@ -41,6 +41,5 @@ Learn about our data structures.
 
 installation
 input_output
-sample_data
 movement_dataset
 ```

From c15cd9e34b1a87ded1fdf48540ad2d590bf8e84b Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Fri, 29 Nov 2024 15:42:28 +0000
Subject: [PATCH 07/10] remove redirects

---
 docs/requirements.txt |  1 -
 docs/source/conf.py   | 11 -----------
 2 files changed, 12 deletions(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 0cc06524..0a950f2e 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -8,6 +8,5 @@ sphinx
 sphinx-autodoc-typehints
 sphinx-design
 sphinx-gallery
-sphinx-reredirects
 sphinx-sitemap
 tables
diff --git a/docs/source/conf.py b/docs/source/conf.py
index ecdeddef..79e51abb 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -46,7 +46,6 @@
     "nbsphinx",
     "sphinx_design",
     "sphinx_gallery.gen_gallery",
-    "sphinx_reredirects",
     "sphinx_sitemap",
     "sphinx.ext.autosectionlabel",
 ]
@@ -115,16 +114,6 @@
     # do not render config params set as # sphinx_gallery_config [= value]
 }
 
-# Set up redirects for pages that were renamed or moved
-# using the sphinx-reredirects extension.
-# See: https://documatt.com/sphinx-reredirects/usage.html
-redirects = {
-    # from the old "getting_started" folder to the new "user_guide" folder
-    "getting_started/index": "../user_guide/index.html",
-    "getting_started/input_output": "../user_guide/input_output.html",
-    "getting_started/installation": "../user_guide/installation.html",
-    "getting_started/movement_dataset": "../user_guide/movement_dataset.html",
-}
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

From fdadf5d9e39dac87b0be68558c306aaefc906700 Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Sat, 30 Nov 2024 16:41:24 +0000
Subject: [PATCH 08/10] configure custon notfound (404) page

---
 docs/requirements.txt |  1 +
 docs/source/conf.py   | 20 ++++++++++++++++++++
 2 files changed, 21 insertions(+)

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/conf.py b/docs/source/conf.py
index 79e51abb..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",
@@ -206,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": """
+<h1>Page Not Found</h1>
+
+<p>Sorry, we couldn't find that page.</p>
+
+<p>We occasionally restructure the movement website, and some links may have broken.</p> 
+
+<p>Try using the search box or go to the homepage.</p>
+""",
+}
+
+# needed for GH pages (vs readthedocs),
+# because we have no '/<language>/<version>/' in the URL
+notfound_urls_prefix = None

From 96ccbc6e4a5d4be5b8a60192f4ea0868a477d2aa Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Sat, 30 Nov 2024 16:48:28 +0000
Subject: [PATCH 09/10] use sentence capitalisation in section headings

---
 docs/source/_templates/api_index_head.rst | 2 +-
 docs/source/index.md                      | 2 +-
 docs/source/user_guide/index.md           | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

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/index.md b/docs/source/index.md
index 3763998e..43aba6df 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -6,7 +6,7 @@ A Python toolbox for analysing animal body movements across space and time.
 ::::{grid} 1 2 2 3
 :gutter: 3
 
-:::{grid-item-card} {fas}`book;sd-text-primary` User Guide
+:::{grid-item-card} {fas}`book;sd-text-primary` User guide
 :link: user_guide/index
 :link-type: doc
 
diff --git a/docs/source/user_guide/index.md b/docs/source/user_guide/index.md
index f3222a5a..e8caa8cf 100644
--- a/docs/source/user_guide/index.md
+++ b/docs/source/user_guide/index.md
@@ -1,4 +1,4 @@
-# User Guide
+# User guide
 
 Start by [installing the package](installation.md) and
 [loading your own tracking data](input_output.md), or playing with some

From 072f648a6b78ae84074fc223bac8512269327e11 Mon Sep 17 00:00:00 2001
From: lochhh <changhuan.lo@ucl.ac.uk>
Date: Mon, 2 Dec 2024 17:51:48 +0000
Subject: [PATCH 10/10] Empty commit