Merge branch '274-document-form-fields' into 'django'

Resolve "Document form fields"

Closes #274

See merge request !141

django/allgo/main/forms.py

@@ -2,6 +2,8 @@ from allauth.account.forms import SignupForm
 from django import forms
 from django.contrib.auth.models import User
 from django.core.validators import RegexValidator
+from django.utils.safestring import mark_safe
+
 from taggit.forms import TagField
 
 import config
@@ -42,7 +44,8 @@ class SSHForm(forms.ModelForm):
     sshkey = forms.CharField(
             label="SSH Key",
             label_suffix='',
-            widget=forms.Textarea)
+            widget=forms.Textarea,
+            help_text=mark_safe('Before you can add an SSH key you need to <a href="https://gitlab.inria.fr/help/ssh/README#generating-a-new-ssh-key-pair">generate one</a> or use an <a href="https://gitlab.inria.fr/help/ssh/README#locating-an-existing-ssh-key-pair">existing key.</a>'),)
 
     class Meta:
         model = AllgoUser
@@ -56,7 +59,7 @@ class UserWebappForm(forms.ModelForm):
     description = forms.CharField(widget=forms.Textarea, label_suffix='')
     contact = forms.EmailField(required=False, label="Contact", label_suffix='')
     notebook_gitrepo = forms.URLField(required=False, label="Notebook repository", label_suffix="")
-    owner = forms.CharField(required=False, label="Owner", label_suffix='')
+    owner = forms.CharField(required=False, label="Owner", label_suffix='', help_text="Username of the new owner of the application. You will immediately loose access to the application.")
     tags = TagField(label_suffix='')
     memory_limit_mb = forms.IntegerField(label="Memory limit", label_suffix='',
             min_value=0)
@@ -97,19 +100,22 @@ class HomeSignupForm(SignupForm):
 class JobForm(forms.ModelForm):
     version = forms.CharField(
             label = 'Version',
-            label_suffix='')
+            label_suffix='',
+            help_text='Version of the application')
     files = forms.FileField(
             widget=forms.FileInput(attrs={'multiple': True}),
             required=False,
             label='Files to upload',
-            label_suffix='')
+            label_suffix='',
+            help_text='Click "Choose file" to select and upload your job\'s  input files')
     queue_id = forms.ModelChoiceField(
             queryset=JobQueue.objects.all().distinct(),
             initial=1,
             label='Queue',
             label_suffix='',
+            help_text=mark_safe('The <a href="https://allgo.gitlabpages.inria.fr/doc/run.html?highlight=queue#queue">queue for scheduling your job</a>. Queues with shorter limit have a higher priority.'),
             )
-    param = forms.CharField(label='Parameters', label_suffix='', required=False)
+    param = forms.CharField(label='Parameters', label_suffix='', required=False, help_text='Enter the parameters you need or click on the "presets" button to select any predefined one.')
     webapp_parameters = forms.ModelChoiceField(
             queryset=WebappParameter.objects.all(),
             label="presets",
@@ -162,7 +168,7 @@ class WebappForm(forms.ModelForm):
 
     # Basic
     name = forms.CharField(label="Application name", label_suffix="")
-    contact = forms.EmailField(label="Email contact", label_suffix="", required=False)
+    contact = forms.EmailField(label="Email contact", label_suffix="", required=False, help_text="By default this will be your personnal e-mail address. You may fill this field if you wish to use a different contact address.")
     description = forms.CharField(widget=forms.Textarea, label="Description", label_suffix="")
     private = forms.TypedChoiceField(
             coerce=lambda x: x == 'True',
@@ -170,6 +176,7 @@ class WebappForm(forms.ModelForm):
             initial=True,
             label="Private mode",
             label_suffix='',
+            help_text='Private apps do not appears in the public list, but they are reachable by users knowing the url.',
             widget=forms.RadioSelect)
 
     # Advanced
@@ -183,8 +190,10 @@ class WebappForm(forms.ModelForm):
     job_queue = forms.ModelChoiceField(
             queryset=JobQueue.objects.all().distinct().order_by("timeout"),
             label='Default job queue',
+            help_text=mark_safe('The default <a href="https://allgo.gitlabpages.inria.fr/doc/deploy.html#queue">queue for scheduling new jobs</a> using this app.'),
             label_suffix='')
     entrypoint = forms.CharField(label="Entrypoint", label_suffix="",
+            help_text=mark_safe('This is the <a href="https://allgo.gitlabpages.inria.fr/doc/deploy.html#entrypoint">command executed when allgo runs a job</a> for this app.'),
             initial="/home/allgo/entrypoint")
 
     def __init__(self, *args, **kwargs):

django/allgo/templates/user_ssh_add.html

@@ -16,12 +16,7 @@
 
           <div class="form-group">
           {{ form.sshkey.label_tag }}
-          <small class="form-text text-muted">
-            Before you can add an SSH key you need to
-            <a href="https://gitlab.inria.fr/help/ssh/README#generating-a-new-ssh-key-pair">generate one</a>
-            or use an
-            <a href="https://gitlab.inria.fr/help/ssh/README#locating-an-existing-ssh-key-pair">existing key.</a>
-          </small>
+          <small class="form-text text-muted">{{ form.sshkey.help_text }}</small>
           {{ form.sshkey | attr:"placeholder:Example ssh-rsa ...." | add_class:"form-control" }}
           </div>
 

django/allgo/templates/webapp_add.html

@@ -41,7 +41,8 @@
                 <div class="col">
                   <div class="form-group">
                     {{ form.contact.label_tag }}
-                    {{ form.contact | attr:"placeholder:If different from you" | add_class:"form-control" }}
+                    {{ form.contact | attr:"placeholder:john.smith@example.net" | add_class:"form-control" }}
+                    <small class="form-text text-muted">{{ form.contact.help_text }}</small>
                   </div>
                 </div>
               </div>
@@ -49,18 +50,25 @@
               <div class="form-group">
                 {{ form.description.label_tag }}
                 {{ form.description | attr:"placeholder:Consider it as the app README file" | add_class:"form-control" }}
-                <small id="descriptionHelp" class="form-text text-muted"><a href="https://daringfireball.net/projects/markdown/syntax" title="Markdown syntax">Mardown syntax</a> is used for formatting.</small>
+                <small class="form-text text-muted"><a href="https://daringfireball.net/projects/markdown/syntax" title="Markdown syntax">Mardown syntax</a> is used for formatting.</small>
               </div>
 
               <div class="form-group">
                 {{ form.private.label_tag }}
                 <div class="btn-group btn-group-toggle" data-toggle="buttons">
                 {% for private_field in form.private %}
-                  <label class="btn btn-secondary active">
-                    <input type="{{ private_field.data.type }}" id="{{ private_field.id_for_label }}" value="{{ private_field.data.value }}" name="{{ private_field.data.name }}" {% if private_field.data.selected %}checked{% endif %}>{{ private_field.choice_label }}
-                  </label>
+                <label class="btn btn-secondary">
+                  <input 
+                    type="{{ private_field.data.type }}"
+                    id="{{ private_field.id_for_label }}"
+                    value="{{ private_field.data.value }}"
+                    name="{{ private_field.data.name }}"
+                    {% if private_field.data.selected %}checked{% endif %}>
+                  {{ private_field.choice_label }}
+                </label>
                 {% endfor %}
                 </div>
+                  <small class="form-text text-muted">{{ form.private.help_text }}</small>
               </div>
 
             </div>
@@ -100,6 +108,7 @@
                     >{{ choice | fancy_job_queue }}</option>
                   {% endfor %}
                 </select>
+                <small class="form-text text-muted">{{ form.job_queue.help_text }}</small>
               </div>
 
               <div class="form-group col-md-6">
@@ -107,6 +116,7 @@
                 <div class="input-group">
                   {{ form.entrypoint | add_class:"form-control" }}
                 </div>
+                <small class="form-text text-muted">{{ form.entrypoint.help_text }}</small>
               </div>
 
             </div>

django/allgo/templates/webapp_detail.html

@@ -68,7 +68,7 @@
     {% endif %}
 
     {# Panels #}
-    <ul class="nav nav-tabs">
+    <ul class="nav nav-tabs mt-3">
       <li class="nav-item"><a class="nav-link active" data-toggle="tab" href="#create-job"><i class="fas fa-database"></i> Run a job</a></li>
       <li class="nav-item"><a class="nav-link" data-toggle="tab" href="#api"><i class="fas fa-terminal"></i> Use the API</a></li>
       {% if webapp.notebook_gitrepo %}
@@ -86,6 +86,7 @@
             <div class="form-group">
               {{ form.files.label_tag }}
               <input type="file" class="form-control-file filestyle" name="{{ form.files.name }}" id="inputGroupFile01" data-buttonBefore="true" data-badge="true"  multiple>
+              <small class="form-text text-muted">{{ form.files.help_text }}</small>
             </div>
 
             {{ form.param | label_with_classes:"d-block" }}
@@ -96,11 +97,14 @@
                   <div class="dropdown-menu">
                     {% for choice in form.webapp_parameters.field.queryset %}
                       <a class="dropdown-item" href="#" data-param="{{ choice.value }}">{{ choice.name }}</a>
+                    {% empty %}
+                    <p class="dropdown-item">No presets available</p>
                     {% endfor %}
                   </div>
                 </div>
-                {{ form.param | attr:"placeholder:Type your parameters" | add_class:"form-control dropdown-value" }}
+                {{ form.param | attr:"placeholder:Type your parameters here" | add_class:"form-control dropdown-value" }}
               </div>
+              <small class="form-text text-muted">{{ form.param.help_text }}</small>
             </div>
 
             <div class="row">
@@ -111,7 +115,9 @@
                   <option value="{{ choice }}">{{ choice }}</option>
                   {% endfor %}
                 </select>
+                <small class="form-text text-muted">{{ form.version.help_text }}</small>
               </div>
+
               <div class="col form-group">
                 {{ form.queue_id.label_tag }}
 
@@ -122,10 +128,11 @@
                     >{{ choice | fancy_job_queue }}</option>
                   {% endfor %}
                 </select>
+                <small class="form-text text-muted">{{ form.queue_id.help_text }}</small>
               </div>
             </div>
 
-            <input class="btn btn-primary float-right" type="submit" value="Run this job">
+            <input class="btn btn-primary" type="submit" value="Run this job">
         </form>
 
 

django/allgo/templates/webapp_update.html

@@ -40,7 +40,8 @@
 
               <div class="form-group">
                 {{ form.owner.label_tag }}
-                {{ form.owner | attr:"placeholder:Enter the owner username" | add_class:"form-control" }}
+                {{ form.owner | attr:"placeholder:Enter the new owner username" | add_class:"form-control" }}
+                <small class="form-text text-muted">{{ form.owner.help_text }}</small>
               </div>
 
               <div class="form-group">