Plan UI usability (adding expedition.yaml guidance) (#277)

* remove duplicates and add thumbnail for surf tutorials

* add tutorial doc on how to ineract with expedition.yaml

* point to information on expedition.yaml in rest of docs

* point to docs in yaml file

* update yaml guidance thumbnail

* use relative paths

* fix thumbnails

* remove duplicate note/tip

* post review edits

* Apply suggestions from code review

Co-authored-by: Erik van Sebille <erikvansebille@gmail.com>

* edits post code review

---------

Co-authored-by: Erik van Sebille <erikvansebille@gmail.com>

Author: j-atkins

docs/conf.py

@@ -80,6 +80,9 @@
     "user-guide/teacher-content/ILOs": "user-guide/_images/ILOs.jpg",
     "user-guide/teacher-content/UU-ocean-of-future/Tutorial1": "user-guide/_images/freepik_assignment.png",
     "user-guide/teacher-content/UU-ocean-of-future/Tutorial2": "user-guide/_images/freepik_assignment.png",
+    "user-guide/tutorials/surf_collaborative_setup": "user-guide/_images/freepik_research_vessel.jpg",
+    "user-guide/tutorials/surf_research_cloud_setup": "user-guide/_images/freepik_research_vessel.jpg",
+    "user-guide/tutorials/working_with_expedition_yaml": "user-guide/_images/AnnaWeber.jpeg",
 }
 
 sphinx_gallery_conf = {"default_thumb_file": "_static/virtual_ship_logo.png"}

docs/user-guide/assignments/Sail_the_ship.ipynb

@@ -156,6 +156,11 @@
     "\n",
     "The next step is to finalise the expedition schedule plan, including setting times and instrument selection choices for each waypoint, as well as configuring the ship (including any underway measurement instruments). \n",
     "\n",
+    "<div class=\"alert alert-block alert-info\"> \n",
+    "**NOTE**: This section describes the process of finalising the expedition schedule and instrument selection using the `virtualship plan` application. For expeditions with many waypoints, it can become cumbersome to use the planning tool (note, using VirtualShip in a remote terminal / cloud-based environment can also introduce lag in the user-interface). **In this case, you may prefer to edit the** `expedition.yaml` **file directly (see [here](../tutorials/working_with_expedition_yaml.md) for more details on how to do so)**.\n",
+    "</div>\n",
+    "\n",
+    "\n",
     "The easiest way to do so is to use the bespoke VirtualShip planning tool. Enter the following command in Terminal: `virtualship plan EXPEDITION_NAME`.\n",
     "\n",
     "<div class=\"alert alert-block alert-success\"> \n",

docs/user-guide/quickstart.md

@@ -58,16 +58,16 @@ For advanced users: it is also possible to run the expedition initialisation ste
 
 ## 3) Expedition scheduling & ship configuration
 
+```{important}
+This section describes the process of finalising the expedition schedule and instrument selection using the `virtualship plan` application. This is the recommended way for most users but when expeditions become larger with many waypoints, it can become cumbersome to use the planning tool (note, using VirtualShip in a remote terminal / cloud-based environment can also introduce lag in the user-interface). **In this case, you may prefer to edit the `expedition.yaml` file directly (see [here](./tutorials/working_with_expedition_yaml.md) for more details on how to do so)**.
+```
+
 The next step is to finalise the expedition schedule plan, including setting times and instrument selection choices for each waypoint, as well as configuring the ship (such as its speed and underway measurement instruments). The easiest way to do so is to use the bespoke VirtualShip planning tool via the following command:
 
 ```
 virtualship plan EXPEDITION_NAME
 ```
 
-```{tip}
-Using the `virtualship plan` tool is optional. Advanced users can also edit the `expedition.yaml` file directly if preferred.
-```
-
 The planning tool should look something like this and offers an intuitive way to make your selections:
 
 ![example_plan_app](example_plan_app.gif)

docs/user-guide/tutorials/index.md

@@ -5,8 +5,6 @@
 maxdepth: 1
 caption: Post-processing results
 ---
-surf_research_cloud_setup.ipynb
-surf_collaborative_setup.ipynb
 ADCP_data_tutorial.ipynb
 CTD_data_tutorial.ipynb
 Drifter_data_tutorial.ipynb
@@ -25,3 +23,11 @@ caption: SURF Research Cloud set up
 surf_research_cloud_setup.ipynb
 surf_collaborative_setup.ipynb
 ```
+
+```{nbgallery}
+---
+maxdepth: 1
+caption: Miscellaneous
+---
+working_with_expedition_yaml.md
+```

docs/user-guide/tutorials/working_with_expedition_yaml.md

@@ -0,0 +1,105 @@
+## Working with the `expedition.yaml` file
+
+This tutorial will guide you through the structure of the `expedition.yaml` file and how to modify it.
+
+The `expedition.yaml` file is ingested by `virtualship run` and is used to configure expeditions. It contains metadata and settings that define the parameters of an expedition, including information about ship speed, instrument configurations, waypoint timings and instrument selections.
+
+This tutorial describes an alternative means to using the `virtualship plan` command, which provides a user-friendly interface for interacting with `expedition.yaml` but can become cumbersome for long, complex expeditions with many waypoints and instruments. Interacting with the `expedition.yaml` file directly tends to be faster for larger expeditions and experienced users.
+
+### Editing the file
+
+The `expedition.yaml` file can be opened and edited using any text editor that supports YAML format. Make your changes and save the file to write the changes to your expedition directory.
+
+```{tip}
+The `expedition.yaml` file can also be opened and edited in Jupyter Lab environments using the built-in text editor. Simply navigate to the file in the file browser and (double) click to open it in a new tab.
+```
+
+```{important}
+The `expedition.yaml` file is highly sensitive to indentation and formatting, so please ensure that you maintain the correct formatting (as described [below](#specifics-for-each-section)) when making modifications.
+```
+
+### Structure
+
+The `expedition.yaml` file is written in [YAML](https://en.wikipedia.org/wiki/YAML) format, which is a human-readable data serialization standard. Below is an annotated example of a simple `expedition.yaml` file with two waypoints:
+
+```yaml
+# EXAMPLE EXPEDITION.YAML
+#
+schedule: # <-- 1. expedition schedule section
+  waypoints:
+    - instrument: # <-- Waypoint 1
+        - CTD
+        - CTD_BGC
+        - ARGO_FLOAT
+        - DRIFTER
+      location:
+        latitude: 45.604174
+        longitude: -43.886739
+      time: 1998-03-08 03:37:00
+    - instrument: # <-- Waypoint 2
+        - ARGO_FLOAT
+        - DRIFTER
+        - XBT
+      location:
+        latitude: 48.185988
+        longitude: -32.988302
+      time: 1998-03-10 03:05:00
+#
+instruments_config: # <-- 2. instrument configuration section
+  adcp_config:
+    num_bins: 40
+    max_depth_meter: -1000.0
+    period_minutes: 5.0
+  ship_underwater_st_config:
+    period_minutes: 5.0
+  argo_float_config: ...
+  ctd_bgc_config: ...
+  ctd_config: ...
+  drifter_config: ...
+  xbt_config: ...
+#
+ship_config: # <-- 3. ship configuration section
+  ship_speed_knots: 10.0
+```
+
+```{note}
+In the example above, some instrument configuration parameters are replaced by ellipses (`...`) for brevity. In a real `expedition.yaml` file, these sections would contain detailed configuration settings for each instrument.
+```
+
+### Specifics for each section
+
+#### 1. `schedule`
+
+This section contains a list of `waypoints` that define the expedition's route. Each waypoint includes:
+
+- **Instruments (`instrument`)**: A list of instruments to be deployed at that waypoint. Add or remove instruments by adding or deleting entries on _new lines_. The instrument selection can also be left empty (i.e., no instruments deployed at that waypoint) by setting the parameter to: `instrument: null`.
+
+```{tip}
+Full list of instruments supported for deployment at waypoints (case-sensitive): `CTD`, `CTD_BGC`, `DRIFTER`, `ARGO_FLOAT`, `XBT` (or `null`).
+```
+
+- **Location (`location`)**: The geographical coordinates (latitude and longitude) of the waypoint. These must be in decimal degrees (DD) format and within valid ranges: latitude between -90 and 90, longitude between -180 and 180.
+
+- **Time (`time`)**: The scheduled time for reaching the waypoint, specifically in YYYY-MM-DD HH:MM:SS format.
+
+#### 2. `instruments_config`
+
+This section defines the configuration settings for each instrument used in the expedition. Each instrument has its own subsection where specific parameters can be set.
+
+Because **underway instruments** (e.g., ADCP, Ship Underwater ST) collect data continuously while the ship is moving, their deployment is not tied to specific waypoints. Instead, the presence of their configuration sections in `instruments_config` indicates that they will be active throughout the expedition. This means that if you wish to turn off an underway instrument, you can remove its configuration section or simply set it to `null`, for example:
+
+```yaml
+instruments_config:
+  adcp_config: null
+  ship_underwater_st_config: null
+```
+
+For **all other instruments**, e.g. CTD, ARGO_FLOAT etc., the parameters can often be left as the default values unless advanced customisations are required.
+
+#### 3. `ship_config`
+
+This section contains setting related to the ship itself, specifically:
+
+- **Ship speed (`ship_speed_knots`)**: The speed of the ship in knots (nautical miles per hour; where 1 knot = 1.852 km/h). Note in most cases this should be left as the default value unless there is a specific reason to change it.
+
+<!-- TODO: more details on ship configuration if added in the future -->

src/virtualship/static/expedition.yaml

@@ -1,3 +1,5 @@
+# see https://virtualship.readthedocs.io/en/latest/user-guide/tutorials/working_with_expedition_yaml.html for more details on how to edit this file
+#
 schedule:
   waypoints:
     - instrument:

tests/expedition/expedition_dir/expedition.yaml

@@ -1,3 +1,5 @@
+# see https://virtualship.readthedocs.io/en/latest/user-guide/tutorials/working_with_expedition_yaml.html for more details on how to edit this file
+#
 schedule:
   waypoints:
     - instrument: