Restructure "Getting Started" page to a "User Guide" - take 2

docs/requirements.txt

@@ -8,5 +8,6 @@ sphinx
 sphinx-autodoc-typehints
 sphinx-design
 sphinx-gallery
+sphinx-notfound-page
 sphinx-sitemap
 tables

docs/source/_templates/api_index_head.rst

@@ -3,7 +3,7 @@
 
 .. _target-api:
 
-API Reference
+API reference
 =============
 
 Information on specific functions, classes, and methods.

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": """
+<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

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

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
+```

docs/source/getting_started/input_output.md → 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.
+:::