Updates to Examples section

README.md

@@ -47,7 +47,7 @@ sphinx-build -b html ./docs/source ./docs/html
 ```
 Sometimes the cache needs to be cleared for internal links to update. If facing this problem, run this from the PolarRoute directory.
 ```
-rm -r docs/build/.doctrees/
+rm -r docs/html/.doctrees/
 ```
 ## Developers
 Jonathan Smith, Samuel Hall, George Coombs, James Byrne,  Michael Thorne, Maria Fox, Harrison Abbot, Ayat Fekry

docs/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: e15f2ed5b32773b0295f228f51a3b4e6
+config: 9148f976cde425ab5b276686e1a054e9
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/html/_sources/sections/Configuration/Route_planning_config.rst.txt

@@ -1,3 +1,5 @@
+.. _route config:
+
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Configuration - Route Planning
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/html/_sources/sections/Examples.rst.txt

@@ -6,8 +6,8 @@ The CLI provides multiple entry-points through which the PolarRoute package can
 :ref:`Command Line Interface <cli>` section of these docs.
 
 To summarise, the basic process is to create an environment mesh, add vehicle performance characteristics to each
-cellbox in that mesh, then find an optimal route between waypoints in that mesh. At any stage, GeoPlot can be used 
-to visualise the outputs.
+cell in that mesh and then find an optimal route between waypoints located within that mesh. At any stage, `GeoPlot <https://github.com/antarctica/GeoPlot>`_
+can be used to visualise the outputs.
 
 ::
 
@@ -23,23 +23,31 @@ to visualise the outputs.
 
 
 Above are the commands to run in order to fulfill this process. If you have successfully installed PolarRoute and would
-like to try, :download:`here<https://raw.githubusercontent.com/antarctica/PolarRoute/main/docs/source/sections/Examples/example_3.zip>` is some example data which you can use. Simply extract the configs
-out of the zip archive, and run the commands on the appropriate files. To map the commands to the files in the zip archive:
+like to try it out, :download:`here<https://raw.githubusercontent.com/antarctica/PolarRoute/main/docs/source/sections/Examples/example_3.zip>`
+is some example data which you can use. Simply extract the configs out of the zip archive, and run the commands on the
+appropriate files. To map the commands to the files in the zip archive:
 
 * :code:`<mesh_config_file>` is called :code:`grf_example.config.json`
 * :code:`<vessel_config_file>` is called :code:`ship.config.json`
 * :code:`<route_config_file>` is called :code:`traveltime.config.json`
 * :code:`<waypoints_file>` is called :code:`waypoints_example.csv`
 
-Several notebooks have been created that will guide you through each stage in PolarRoute, from mesh creation through to route planning. 
-These notebooks use the CLI entry-points to show how someone would typically interact with PolarRoute through the terminal.
+.. note::
+    By default the :code:`plot_mesh` command will plot a basemap showing the location of your mesh on Earth.
+    When working with entirely synthetic data, e.g. when running any of the GRF examples below, the spatial coordinates
+    used do not correspond to a real location and we recommend running :code:`plot_mesh` with the :code:`-b` option to
+    disable this basemap.
+
+Several notebooks have been created that will guide you through each stage in using PolarRoute, from mesh creation
+through to route planning. These notebooks are available via Google Colab and use the CLI entry-points to show how
+someone would typically interact with PolarRoute through the terminal.
 
 ^^^^^^^^^^^^^^^^^^
 Empty Mesh Example 
 ^^^^^^^^^^^^^^^^^^
 Here we provide two examples of empty meshes that are simple to process to get you started. Since these are empty meshes,
-we expect the optimal calculated route to be a straight line between two waypoints, which is seen as a great circle arc on
-the mercator projection that GeoPlot provides. 
+we expect the optimal calculated route to be a straight line between two waypoints. Over long distances this is seen as
+a great circle arc on the mercator projection that GeoPlot uses to display the mesh.
 
 * :download:`Uniform Mesh<https://raw.githubusercontent.com/antarctica/PolarRoute/main/docs/source/sections/Examples/example_1.zip>`
 * :download:`Non-Uniform Mesh<https://raw.githubusercontent.com/antarctica/PolarRoute/main/docs/source/sections/Examples/example_2.zip>`
@@ -48,19 +56,20 @@ the mercator projection that GeoPlot provides.
 ^^^^^^^^^^^^^^^^^^^^^^
 Synthetic Data Example 
 ^^^^^^^^^^^^^^^^^^^^^^
-In this example, we provide synthetic data in the form of Gaussian Random Fields, which provide a random, yet somewhat
+In this example, we provide synthetic data in the form of Gaussian Random Fields (GRFs), which provide a random, yet somewhat
 realistic representation of real-world features such as bathymetry. Here we walk through every step involved in PolarRoute, 
-from creating the mesh through to optimising a route through it. 
+from creating the mesh through to optimising a route within it.
 
 * :download:`Gaussian Random Field data<https://raw.githubusercontent.com/antarctica/PolarRoute/main/docs/source/sections/Examples/example_3.zip>`
 * `Synthetic Data Example <https://colab.research.google.com/drive/1BOzTyBjpCbAJ6PMJi0GS55shuaMu72h5?usp=sharing>`_
 
 ^^^^^^^^^^^^^^^^^
 Real Data Example 
 ^^^^^^^^^^^^^^^^^
-Real world data has been used to generate these meshes around the coast of Antarctica. This data is publically available,
+Real world data has been used to generate these meshes around the coast of Antarctica. This data is publicly available,
 however is not included here to avoid violating data sharing policies. Instead, we provide a mesh file after the 'create_mesh' stage 
-since that is a derived product. See `Dataloaders <https://antarctica.github.io/MeshiPhi/html/sections/Dataloaders/overview.html>`_ 
+since that is a derived product. The data files used to construct the mesh can be seen in the :code:`data_sources` field of
+the config contained within the provided mesh. See `Dataloaders <https://antarctica.github.io/MeshiPhi/html/sections/Dataloaders/overview.html>`_
 in the MeshiPhi docs for more info on each source of data that PolarRoute currently supports.
 
 * :download:`Real-world data 1<https://raw.githubusercontent.com/antarctica/PolarRoute/main/docs/source/sections/Examples/example_4.zip>`
@@ -97,8 +106,8 @@ Loading configuration from *json* file:
 
 The **EnvironmentMesh** object can then be initialised. This mesh object will be constructed using the parameters in its
 configuration file. This mesh object can then be manipulated further, such as increasing its resolution through further
-splitting, adding additional data sources or altering its configuration parameters. See `MeshiPhi <https://github.com/antarctica/MeshiPhi>`_
-docs for a more in-depth explanation. The **EnvironmentMesh** object can then be cast to a json object and saved to a file.
+splitting, adding additional data sources or altering its configuration parameters. See the relevant section of the `MeshiPhi docs <https://antarctica.github.io/MeshiPhi/html/sections/Configuration/Mesh_construction_config.html>`_
+for a more in-depth explanation. The **EnvironmentMesh** object can then be cast to a json object and saved to a file.
 ::
 
     from meshiphi.mesh_generation.mesh_builder import MeshBuilder
@@ -121,8 +130,9 @@ docs for a more in-depth explanation. The **EnvironmentMesh** object can then be
 Simulating a Vessel in a Digital Environment
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Once a digital environment **EnvironmentMesh** object has been created with `MeshiPhi <https://github.com/antarctica/MeshiPhi>`_, a vessel's performance when travelling within it may be simulated. The **VesselPerformanceModeller**
-object requires a digital environment in *json* format and vessel specific configuration parameters, also in *json* format. These may either
+Once a digital environment **EnvironmentMesh** object has been created with `MeshiPhi <https://github.com/antarctica/MeshiPhi>`_,
+a vessel's performance when travelling within it may be simulated. The **VesselPerformanceModeller** object requires a
+digital environment in *json* format and vessel specific configuration parameters, also in *json* format. These may either
 be loaded from a file, or created within any python interpreter.
 
 Loading mesh and vessel from *json* files:
@@ -136,8 +146,8 @@ Loading mesh and vessel from *json* files:
     with open('/path/to/ship.json', 'r') as f:
         vessel = json.load(f) 
 
-The **VesselPerformanceModeller** object can then be initialised. This can be used to simulate the performance of the vessel and encode this information
-into the digital environment.
+The **VesselPerformanceModeller** object can then be initialised. This can be used to simulate the performance of the
+vessel and encode this information into the digital environment.
 ::
 
    from polar_route.vessel_performance.vessel_performance_modeller import VesselPerformanceModeller
@@ -158,15 +168,17 @@ console.
 ^^^^^^^^^^^^^^^^^^
 Route Optimisation
 ^^^^^^^^^^^^^^^^^^
-Now that the vessel dependent environmental mesh is defined, and represented in the `VesselPerformanceModeller` object, we can
-construct routes, with parameters defined by the user in the configuration file. Waypoints are passed as an input 
-file path, `waypoints.csv`, discussed more in the Inputs section of the manual pages.  The route construction is done 
-in two stages: construction of the meshed dijkstra optimal routes, `.compute_routes()`; and, the smoothing of the 
-dijkstra routes to further optimise the solution and reduce mesh dependencies, `.compute_smooth_routes()`. 
-During `.compute_routes()` the paths are appended to the object as an entry `paths`, which are replaced by the 
-smoothed paths after running `.compute_smooth_routes()`. An additional entry `waypoints` is generated to give the 
-waypoints information used in route construction. For further info about the structure of the outputs of the 
-paths please see the Outputs section of the manual.
+Now that the vessel dependent environmental mesh is defined, and represented in the **VesselPerformanceModeller** object,
+we can construct routes, with parameters defined by the user in the :ref:`route config file <route config>`.
+
+Waypoints are passed as an input file path, `waypoints.csv`, discussed more in the Inputs section of the manual pages.
+The route construction is performed in two stages: construction of the meshed dijkstra optimal routes, using
+`.compute_routes()`, and the smoothing of the dijkstra routes to further optimise the solution and reduce mesh
+dependency, using `.compute_smooth_routes()`. During the execution of `.compute_routes()` the paths are stored as an
+attribute of the **RoutePlanner** object under `paths`. These are then replaced by the smoothed paths after running
+`.compute_smooth_routes()`. An additional entry `waypoints` is generated to store the waypoints information used in
+route construction. For further details about the structure of the outputs of the route planner please see the
+:ref:`Outputs` section of this documentation.
 
 ::
 
@@ -189,14 +201,15 @@ paths please see the Outputs section of the manual.
 Visualising Outputs
 ^^^^^^^^^^^^^^^^^^^
 
-The **EnvironmentMesh** object can be visualised using the **GeoPlot** package, also developed by BAS. This package is not included in the distribution
-of MeshiPhi, but can be installed using the following command:
+The **EnvironmentMesh** object can be visualised using the GeoPlot package, also developed by BAS. This package is not
+included in the distribution of PolarRoute, but can be installed using the following command:
 
 :: 
 
     pip install bas_geoplot
 
-**GeoPlot** can be used to visualise the **EnvironmentMesh** object using the following code in an iPython notebook or any python interpreter:
+GeoPlot can then be used to visualise the **EnvironmentMesh** object using the following code in an iPython notebook or
+any python interpreter:
 
 ::
     
@@ -208,7 +221,7 @@ of MeshiPhi, but can be installed using the following command:
     mp.Maps(mesh, 'MeshGrid', predefined='cx')
     mp.Maps(mesh, 'SIC', predefined='SIC')
     mp.Maps(mesh, 'Elevation', predefined='Elev', show=False)
-    mp.Vectors(mesh,'Currents - Mesh', show=False, predefined='Currents')
+    mp.Vectors(mesh,'Currents', show=False, predefined='Currents')
     mp.Vectors(mesh, 'Winds', predefined='Winds', show=False)
 
     mp.show()

docs/html/_static/_sphinx_javascript_frameworks_compat.js

@@ -1,20 +1,9 @@
-/*
- * _sphinx_javascript_frameworks_compat.js
- * ~~~~~~~~~~
- *
- * Compatability shim for jQuery and underscores.js.
- *
- * WILL BE REMOVED IN Sphinx 6.0
- * xref RemovedInSphinx60Warning
+/* Compatability shim for jQuery and underscores.js.
  *
+ * Copyright Sphinx contributors
+ * Released under the two clause BSD licence
  */
 
-/**
- * select a different prefix for underscore
- */
-$u = _.noConflict();
-
-
 /**
  * small helper function to urldecode strings
  *

docs/html/_static/basic.css

@@ -4,7 +4,7 @@
  *
  * Sphinx stylesheet -- basic theme.
  *
- * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */
@@ -324,13 +324,15 @@ aside.sidebar {
 p.sidebar-title {
     font-weight: bold;
 }
+
 nav.contents,
 aside.topic,
 div.admonition, div.topic, blockquote {
     clear: left;
 }
 
 /* -- topics ---------------------------------------------------------------- */
+
 nav.contents,
 aside.topic,
 div.topic {
@@ -606,6 +608,7 @@ ol.simple p,
 ul.simple p {
     margin-bottom: 0;
 }
+
 aside.footnote > span,
 div.citation > span {
     float: left;
@@ -667,6 +670,16 @@ dd {
     margin-left: 30px;
 }
 
+.sig dd {
+    margin-top: 0px;
+    margin-bottom: 0px;
+}
+
+.sig dl {
+    margin-top: 0px;
+    margin-bottom: 0px;
+}
+
 dl > dd:last-child,
 dl > dd:last-child > :last-child {
     margin-bottom: 0;
@@ -735,6 +748,14 @@ abbr, acronym {
     cursor: help;
 }
 
+.translated {
+    background-color: rgba(207, 255, 207, 0.2)
+}
+
+.untranslated {
+    background-color: rgba(255, 207, 207, 0.2)
+}
+
 /* -- code displays --------------------------------------------------------- */
 
 pre {