Add simulation documentation, fix #69

README.md

@@ -34,7 +34,7 @@ Authentication can be provided in two ways:
 
 1. Clone this repository and change into the new directory:
    ```bash
-   gh repo clone digitalfabrik/leeway
+   git clone git@github.com:digitalfabrik/opendrift-leeway-webgui.git leeway
    cd leeway
    ```
 2. Create a virtual environment outside of the project directory and activate it:

opendrift_leeway_webgui/leeway/templates/base.html

@@ -24,7 +24,7 @@
             <p>
                 <a href="https://github.com/digitalfabrik/opendrift-leeway-webgui">Source Code</a>
                 {% if user.is_authenticated %}
-                    | <a href="{% url "simulation_list" %}">List of simulations</a> | <a href="{% url "simulation_form" %}">New Simulation</a> | <a href="{% url "logout" %}">Logout</a>
+                | <a href="{% url "simulation_documentation" %}">Documentation</a> | <a href="{% url "simulation_list" %}">List of simulations</a> | <a href="{% url "simulation_form" %}">New Simulation</a> | <a href="{% url "logout" %}">Logout</a>
                 {% endif %}
             </p>
         </main>

opendrift_leeway_webgui/leeway/templates/leeway/leewaysimulation_documentation.html

@@ -0,0 +1,19 @@
+{% extends "base.html" %}
+{% block content %}
+    <h2>Leeway Simulation Documentation</h2>
+    <h3>Background</h3>
+    <p>This software acts as a web user interface for the <a href="https://opendrift.github.io/gallery/example_leeway.html">OpenDrift Leeway</a> model. The basis for the simulation are experiments performed by the US Coast Guard in 1999. The results are published on <a href="https://ntrl.ntis.gov/NTRL/dashboard/searchResults/titleDetail/ADA366414.xhtml">https://ntrl.ntis.gov</a>, which include desriptions of the objects that were tested (2-13 and following pages).</p>
+    <h3>E-Mail Interface</h3>
+    <p>If you have a low bandwidth connection, you can use the e-mail interface. The simulation parameters can be set in the e-mail subject. Your e-mail address needs to be registered for you user account in this tool first.</p>
+    <ol>
+      <li>Create a new e-mail</li>
+      <li>Enter simulation parameters with adjusted values in the subject: <pre>latitude=33.333;longitude=14.444;duration=48;start_time=2022-12-10 00:00:00</pre></li>
+      <li>Send the mail to <pre>{{ SERVER_EMAIL }}</pre></li>
+    </ol>
+    The default object type for simulatoins is a life raft. The result of the simulation will be sent to your e-mail address within a couple of minutes.
+    <h3>Interpreting Simulation Result</h3>
+    <p>When the simulation is finished, you will receive an e-mail that contains an attached image with the simulation results.</p>
+    <p>The simulation will randomly distribute 100 test particles around your entered coordinates. The default radius for distributing the particles is 1000 meters. If the coordinates are not very clear, you can increase this radius.</p>
+    <p>The starting points of the simulated particles are marked with green dots. If the particle ends up floating in water at the end of the simulation, the particle is marked blue. If the particle ends up on shore, it is marked green.</p>
+    <p>The image shows the trajectories of particles from the starting points to the ending points. The color of the trajectories incdicates the position of a particle at a given time. For example the color green always shows the position of the particles after ~50% of the simulated time range, while orange shows the positions at ~75%.</p>
+{% endblock content %}

opendrift_leeway_webgui/leeway/urls.py

@@ -10,6 +10,7 @@
 
 from .views import (
     IndexRedirectView,
+    LeewaySimulationDocumentation,
     LeewaySimulationCreateView,
     LeewaySimulationDetailView,
     LeewaySimulationListView,
@@ -18,6 +19,11 @@
 #: The url patterns of this module (see :doc:`django:topics/http/urls`)
 urlpatterns = [
     path("", IndexRedirectView.as_view(), name="index"),
+    path(
+        "documentation/",
+        LeewaySimulationDocumentation.as_view(),
+        name="simulation_documentation",
+    ),
     path(
         "simulations/",
         include(

opendrift_leeway_webgui/leeway/views.py

@@ -6,6 +6,7 @@
 from django.views.generic.detail import DetailView
 from django.views.generic.edit import CreateView
 from django.views.generic.list import ListView
+from django.views.generic import TemplateView
 
 from .forms import LeewaySimulationForm
 from .models import LeewaySimulation
@@ -21,6 +22,18 @@ class IndexRedirectView(RedirectView):
     pattern_name = settings.LOGIN_REDIRECT_URL
 
 
+class LeewaySimulationDocumentation(TemplateView):
+    """
+    Display end user documentation for using the tool
+    """
+    template_name = 'leeway/leewaysimulation_documentation.html'
+
+    def get_context_data(self, **kwargs):
+        context = super(LeewaySimulationDocumentation, self).get_context_data(**kwargs)
+        context['SERVER_EMAIL'] = settings.SERVER_EMAIL
+        return context
+
+
 class LeewaySimulationCreateView(LoginRequiredMixin, CreateView):
     """
     The view for rendering and submitting the simulation form