Add help URL in /offliners/{offliner} API endpoint

dispatcher/backend/docs/openapi_v1.yaml

@@ -1033,62 +1033,69 @@ paths:
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  type: object
-                  additionalProperties: true
-                  required:
-                    - key
-                    - type
-                    - label
-                    - required
-                  properties:
-                    key:
-                      type: string
-                      example: username
-                      description: ID/name of the field
-                    type:
-                      type: string
-                      enum:
-                        - text
-                        - hex-color
-                        - url
-                        - email
-                        - integer
-                        - float
-                        - boolean
-                        - string-enum
-                        - list-of-string-enum
-                      description: the type of the field
-                      example: url
-                    label:
-                      type: string
-                      example: Content URL
-                      description: Human representation of the key/name
-                    required:
-                      type: boolean
-                      example: true
-                      description: whether this field's value is required
-                    description:
-                      type: string
-                      example: URL of some information
-                      description: Description to help fill the field
-                    placeholder:
-                      type: string
-                      description: the field's placeholder
-                      example: http://somecontent.tld/here
-                    choices:
-                      description: list of choices to choose a value from
-                      type: array
-                      items:
-                        type: string
-                        example:
-                          - some-value
-                          - another-value
-                    data_key:
-                      type: string
-                      description: actual param name (for when key cant be named the same)
-                      example: api-key
+                type: object
+                properties:
+                  help:
+                    type: string
+                    example: https://github.com/openzim/ted/wiki/Frequently-Asked-Questions
+                    description: URL where help to configure offliner can be found
+                  flags:
+                    type: array
+                    items:
+                      type: object
+                      additionalProperties: true
+                      required:
+                        - key
+                        - type
+                        - label
+                        - required
+                      properties:
+                        key:
+                          type: string
+                          example: username
+                          description: ID/name of the field
+                        type:
+                          type: string
+                          enum:
+                            - text
+                            - hex-color
+                            - url
+                            - email
+                            - integer
+                            - float
+                            - boolean
+                            - string-enum
+                            - list-of-string-enum
+                          description: the type of the field
+                          example: url
+                        label:
+                          type: string
+                          example: Content URL
+                          description: Human representation of the key/name
+                        required:
+                          type: boolean
+                          example: true
+                          description: whether this field's value is required
+                        description:
+                          type: string
+                          example: URL of some information
+                          description: Description to help fill the field
+                        placeholder:
+                          type: string
+                          description: the field's placeholder
+                          example: http://somecontent.tld/here
+                        choices:
+                          description: list of choices to choose a value from
+                          type: array
+                          items:
+                            type: string
+                            example:
+                              - some-value
+                              - another-value
+                        data_key:
+                          type: string
+                          description: actual param name (for when key cant be named the same)
+                          example: api-key
         404:
           description: Not Found
           content:

dispatcher/backend/src/routes/offliners/offliner.py

@@ -35,4 +35,12 @@ def get(self, offliner: str, *args, **kwargs):
 
         schema = ScheduleConfigSchema.get_offliner_schema(offliner)()
 
-        return jsonify(schema.to_desc())
+        return jsonify(
+            {
+                "flags": schema.to_desc(),
+                "help": (  # dynamic + sourced from backend because it might be custom
+                    f"https://github.com/openzim/{offliner}/wiki"
+                    "/Frequently-Asked-Questions"
+                ),
+            }
+        )

dispatcher/backend/src/tests/integration/routes/offliners/test_offliners_routes.py

@@ -0,0 +1,28 @@
+import pytest
+
+from common.enum import Offliner
+
+
+def test_list_offliners(client):
+    url = "/offliners/"
+    response = client.get(url)
+    assert response.status_code == 200
+    response_json = response.get_json()
+    assert "items" in response_json
+    assert "meta" in response_json
+    assert "count" in response_json["meta"]
+    assert len(response_json["items"]) == response_json["meta"]["count"]
+
+
+@pytest.mark.parametrize("offliner", Offliner.all())
+def test_get_offliner(client, offliner):
+    url = f"/offliners/{offliner}"
+    response = client.get(url)
+    assert response.status_code == 200
+    response_json = response.get_json()
+    assert "flags" in response_json
+    assert "help" in response_json
+    assert (
+        response_json["help"]
+        == f"https://github.com/openzim/{offliner}/wiki/Frequently-Asked-Questions"
+    )

dispatcher/frontend-ui/src/components/ScheduleEditor.vue

@@ -290,7 +290,9 @@
       schedule() { return this.$store.getters.schedule || null; },
       editorReady() { return this.schedule && this.edit_schedule && this.flags_definition !== null; },
       edit_task_name() { return this.edit_schedule.config.task_name || this.schedule.config.task_name; },
-      flags_definition() { return this.$store.getters.offliners_defs[this.edit_task_name] || null },
+      offliner_definition() { return this.$store.getters.offliners_defs[this.edit_task_name] || null },
+      flags_definition() { return this.offliner_definition ? this.offliner_definition.flags : null },
+      help() { return this.offliner_definition ? this.offliner_definition.help : null },
       edit_flags_fields() {
         let fields = [];
         for (var i=0;i<this.flags_definition.length;i++) {

dispatcher/frontend-ui/src/constants.js

@@ -274,10 +274,10 @@ function schedule_durations_dict(duration) {
   return multiple_durations(min_value, max_value, duration.workers);
 }
 
-function secret_fields_for(offliner_def) {
-  if (offliner_def === null)
+function secret_fields_for(offliner_flags_definition) {
+  if (offliner_flags_definition === null)
     return [];
-  return offliner_def
+  return offliner_flags_definition
     .filter(function (item) { return "secret" in item && item.secret === true; })
     .map(function (item) { return item.data_key});
 }

dispatcher/frontend-ui/src/views/ScheduleView.vue

@@ -195,9 +195,10 @@
       last_run() { return this.schedule.most_recent_task; },
       config() { return this.schedule.config; },
       offliner() { return this.config.task_name; },
-      offliner_def() { return this.$store.getters.offliners_defs[this.offliner] || null; },
+      offliner_definition() { return this.$store.getters.offliners_defs[this.edit_task_name] || null },
+      flags_definition() { return this.offliner_definition ? this.offliner_definition.flags : null },
       platform() { return this.config.platform; },
-      secret_fields() { return Constants.secret_fields_for(this.offliner_def); },
+      secret_fields() { return Constants.secret_fields_for(this.flags_definition); },
       image_human() { return Constants.image_human(this.config); },
       image_url() { return Constants.image_url(this.config); },
       warehouse_path() { return this.config.warehouse_path; },

dispatcher/frontend-ui/src/views/TaskView.vue

@@ -178,7 +178,8 @@
         return `You are ${Constants.tz_details.offsetstr} (${Constants.tz_details.tz}).`
       },
       offliner() { return this.task.config.task_name; },
-      offliner_def() { return this.$store.getters.offliners_defs[this.offliner] || null; },
+      offliner_definition() { return this.$store.getters.offliners_defs[this.edit_task_name] || null },
+      flags_definition() { return this.offliner_definition ? this.offliner_definition.flags : null },
       sorted_files() { return Object.values(this.task.files).sortBy('created_timestamp'); },
       short_id() { return Constants.short_id(this._id); },
       is_running() { return ["failed", "canceled", "succeeded", "cancel_requested"].indexOf(this.task.status) == -1; },
@@ -208,7 +209,7 @@
         return Constants.format_duration_between(first, last);
       },
       started_on() { return this.task.timestamp.started || this.task.timestamp.reserved; },
-      secret_fields() { return Constants.secret_fields_for(this.offliner_def); },
+      secret_fields() { return Constants.secret_fields_for(this.flags_definition); },
       pipe_duration() { return Constants.format_duration_between(this.task.timestamp.requested, this.task.timestamp.started); },
       zimfarm_logs_url() { return Constants.logs_url(this.task); },
       zimfarm_artifacts_url() { return Constants.artifacts_url(this.task); },