Add Documentation parameter into template definition

server/src/main/scala/de/frosner/broccoli/models/Template.scala

@@ -6,7 +6,7 @@ import play.api.libs.functional.syntax._
 import play.api.libs.json.Json.JsValueWrapper
 import play.api.libs.json._
 
-case class Template(id: String, template: String, description: String, parameterInfos: Map[String, ParameterInfo])
+case class Template(id: String, template: String, documentation_url: String, description: String, parameterInfos: Map[String, ParameterInfo])
     extends Serializable {
 
   @transient
@@ -38,11 +38,12 @@ object Template {
     (
       (JsPath \ "id").write[String] and
         (JsPath \ "description").write[String] and
+        (JsPath \ "documentation_url").write[String] and
         (JsPath \ "parameters").write[Seq[String]] and
         (JsPath \ "parameterInfos").write[Map[String, ParameterInfo]](paramInfoMapWrites) and
         (JsPath \ "version").write[String]
     )((template: Template) =>
-      (template.id, template.description, template.sortedParameters, template.parameterInfos, template.version))
+      (template.id, template.description, template.documentation_url, template.sortedParameters, template.parameterInfos, template.version))
 
   implicit val templatePersistenceReads: Reads[Template] = Json.reads[Template]
 

server/src/main/scala/de/frosner/broccoli/templates/TemplateConfig.scala

@@ -17,6 +17,7 @@ object TemplateConfig {
         val confObj = configOrig.asInstanceOf[ConfigObject]
         val config = confObj.toConfig
         val description = Try(config.getString("description")).toOption
+        val documentation_url = Try(config.getString("documentation_url")).toOption
         val parameters = config
           .getObject("parameters")
           .map {
@@ -42,7 +43,7 @@ object TemplateConfig {
               (paramName, Parameter(maybeName, maybeDefault, maybeSecret, paramType, maybeOrderIndex))
           }
           .toMap
-        TemplateInfo(description, parameters)
+        TemplateInfo(description, documentation_url, parameters)
       } match {
         case Success(e)  => Right(e)
         case Failure(ex) =>
@@ -51,12 +52,12 @@ object TemplateConfig {
       }
   }
 
-  final case class TemplateInfo(description: Option[String], parameters: Map[String, Parameter])
+  final case class TemplateInfo(description: Option[String], documentation_url: Option[String], parameters: Map[String, Parameter])
 
   final case class Parameter(name: Option[String],
                              default: Option[ParameterValue],
                              secret: Option[Boolean],
                              `type`: ParameterType,
                              orderIndex: Option[Int])
 
-}
+} 

server/src/main/scala/de/frosner/broccoli/templates/TemplateSource.scala

@@ -37,6 +37,7 @@ trait TemplateSource {
         id = templateId,
         template = templateString,
         description = templateInfo.description.getOrElse(s"$templateId template"),
+        documentation_url = templateInfo.documentation_url.getOrElse(s""),
         parameterInfos = templateInfo.parameters
           .map { case (id, parameter) => id -> ParameterInfo.fromTemplateInfoParameter(id, parameter) }
       )

server/src/test/resources/de/frosner/broccoli/templates/curl-without-decription/template.conf

@@ -1,3 +1,4 @@
+documentation_url = "#curl-test-docs"
 parameters = {
   "id" = {
     type = raw

server/src/test/resources/de/frosner/broccoli/templates/curl-without-documentation/template.conf

@@ -0,0 +1,14 @@
+description = "A periodic job that sends an HTTP GET request to a specified address every minute."
+parameters = {
+  "id" = {
+    type = raw
+  }
+  "URL" = {
+    default = "localhost:8000"
+    type = raw
+  }
+  "enabled" = {
+    default = true
+    type = raw
+  }
+}

server/src/test/resources/de/frosner/broccoli/templates/curl-without-documentation/template.json

@@ -0,0 +1,82 @@
+{
+    "Job": {
+        "Region": "global",
+        "ID": "{{id}}",
+        "Name": "{{id}}",
+        "Type": "batch",
+        "Priority": 50,
+        "AllAtOnce": false,
+        "Datacenters": [
+            "dc1"
+        ],
+        "Constraints": null,
+        "TaskGroups": [
+            {
+                "Name": "curl-group",
+                "Count": 1,
+                "Constraints": null,
+                "Tasks": [
+                    {
+                        "Name": "curl-task",
+                        "Driver": "raw_exec",
+                        "User": "",
+                        "Config": {
+                            "args": [
+                                "{{URL}}"
+                            ],
+                            "command": "/usr/bin/curl"
+                        },
+                        "Constraints": null,
+                        "Env": null,
+                        "Services": [],
+                        "Resources": {
+                            "CPU": 50,
+                            "MemoryMB": 128,
+                            "DiskMB": 500,
+                            "IOPS": 0,
+                            "Networks": [
+                                {
+                                    "Public": false,
+                                    "CIDR": "",
+                                    "ReservedPorts": null,
+                                    "DynamicPorts": null,
+                                    "IP": "",
+                                    "MBits": 10
+                                }
+                            ]
+                        },
+                        "Meta": null,
+                        "KillTimeout": 5000000000,
+                        "LogConfig": {
+                            "MaxFiles": 10,
+                            "MaxFileSizeMB": 10
+                        },
+                        "Artifacts": null
+                    }
+                ],
+                "RestartPolicy": {
+                    "Interval": 60000000000,
+                    "Attempts": 2,
+                    "Delay": 15000000000,
+                    "Mode": "delay"
+                },
+                "Meta": null
+            }
+        ],
+        "Update": {
+            "Stagger": 0,
+            "MaxParallel": 0
+        },
+        "Periodic": {
+            "Enabled": {{enabled}},
+            "Spec": "0 0/1 * 1/1 * ? *",
+            "SpecType": "cron",
+            "ProhibitOverlap": true
+        },
+        "Meta": null,
+        "Status": "",
+        "StatusDescription": "",
+        "CreateIndex": 0,
+        "ModifyIndex": 0
+    }
+}

server/src/test/resources/de/frosner/broccoli/templates/curl/template.conf

@@ -1,5 +1,5 @@
 description = "A periodic job that sends an HTTP GET request to a specified address every minute."
-
+documentation_url = "#curl-test-docs"
 parameters = {
   "id" = {
     type = raw

server/src/test/scala/de/frosner/broccoli/controllers/InstanceControllerSpec.scala

@@ -65,6 +65,7 @@ class InstanceControllerSpec
         id = "t",
         template = "{{id}} {{secret}}",
         description = "d",
+        documentation_url = "docs",
         parameterInfos = Map(
           "id" -> ParameterInfo("id", None, None, None, ParameterType.Raw, None),
           "secret" -> ParameterInfo(

server/src/test/scala/de/frosner/broccoli/controllers/TemplateControllerSpec.scala

@@ -18,6 +18,7 @@ class TemplateControllerSpec extends PlaySpecification with AuthUtils {
         id = "id",
         template = "template {{id}}",
         description = "description",
+        documentation_url = "#documentation_url",
         parameterInfos = Map(
           "id" -> ParameterInfo(id = "id",
                                 name = Some("myname"),
@@ -44,6 +45,7 @@ class TemplateControllerSpec extends PlaySpecification with AuthUtils {
               JsObject(Map(
                 "id" -> JsString(template.id),
                 "parameters" -> JsArray(Seq(JsString("id"))),
+                "documentation_url" -> JsString("#documentation_url"),
                 "parameterInfos" -> JsObject(Map(
                   "id" -> JsObject(Map(
                     "id" -> JsString("id"),
@@ -69,6 +71,7 @@ class TemplateControllerSpec extends PlaySpecification with AuthUtils {
         id = "id",
         template = "template {{id}}",
         description = "description",
+        documentation_url = "#documentation_url",
         parameterInfos = Map(
           "id" -> ParameterInfo(id = "id",
                                 name = Some("myname"),
@@ -94,6 +97,7 @@ class TemplateControllerSpec extends PlaySpecification with AuthUtils {
             Map(
               "id" -> JsString(template.id),
               "parameters" -> JsArray(Seq(JsString("id"))),
+              "documentation_url" -> JsString("#documentation_url"),
               "parameterInfos" -> JsObject(Map(
                 "id" -> JsObject(Map(
                   "id" -> JsString("id"),

server/src/test/scala/de/frosner/broccoli/controllers/WebSocketControllerSpec.scala

@@ -35,6 +35,7 @@ class WebSocketControllerSpec
         id = "t",
         template = "{{id}} {{secret}}",
         description = "d",
+        documentation_url = "#documentation_url",
         parameterInfos = Map(
           "id" -> ParameterInfo("id", None, None, None, ParameterType.Raw, None),
           "secret" -> ParameterInfo(

server/src/test/scala/de/frosner/broccoli/instances/NomadInstancesSpec.scala

@@ -36,6 +36,7 @@ class NomadInstancesSpec
         id = "id",
         template = "{{id}}",
         description = "description",
+        documentation_url = "#documentation_url",
         parameterInfos = Map("id" -> ParameterInfo("id", None, None, None, ParameterType.Raw, None))
       ),
       parameterValues = Map("id" -> StringParameterValue("id"))

server/src/test/scala/de/frosner/broccoli/instances/storage/InstanceStorageSpec.scala

@@ -57,6 +57,7 @@ class InstanceStorageSpec extends Specification {
           id = "1",
           template = "\"{{id}} {{age}}\"",
           description = "desc",
+          documentation_url = "#documentation_url",
           parameterInfos = Map(
             "id" -> ParameterInfo("id", None, None, None, ParameterType.Raw, None),
             "age" -> ParameterInfo("age",
@@ -81,6 +82,7 @@ class InstanceStorageSpec extends Specification {
           id = "1",
           template = "\"{{id}} {{age}}\"",
           description = "desc",
+          documentation_url = "#documentation_url",
           parameterInfos = Map(
             "id" -> ParameterInfo("id", None, None, None, ParameterType.Raw, None),
             "age" -> ParameterInfo("age",

server/src/test/scala/de/frosner/broccoli/instances/storage/couchdb/CouchDBInstanceStorageSpec.scala

@@ -21,6 +21,7 @@ class CouchDBInstanceStorageSpec extends Specification {
     template = Template(id = "t",
                         template = "{{id}}",
                         description = "d",
+                        documentation_url = "#documentation_url",
                         parameterInfos = Map("id" -> ParameterInfo("id", None, None, None, ParameterType.Raw, None))),
     parameterValues = Map(
       "id" -> RawParameterValue("prefix-id")

server/src/test/scala/de/frosner/broccoli/instances/storage/filesystem/FileSystemInstanceStorageSpec.scala

@@ -19,6 +19,7 @@ class FileSystemInstanceStorageSpec extends Specification with TemporaryDirector
     template = Template(id = "t",
                         template = "{{id}}",
                         description = "d",
+                        documentation_url = "#link-to-documentation",
                         parameterInfos = Map("id" -> ParameterInfo("id", None, None, None, ParameterType.Raw, None))),
     parameterValues = Map(
       "id" -> RawParameterValue("prefix-id")

server/src/test/scala/de/frosner/broccoli/models/InstanceSpec.scala

@@ -22,14 +22,14 @@ class InstanceSpec extends Specification with ScalaCheck with ModelArbitraries w
     "be possible to construct if the parameters to be filled match the ones in the template's parameter infos" in {
       val parameterInfos = Map("id" -> ParameterInfo("id", None, None, None, ParameterType.Raw, None))
       val instance1 =
-        Instance("1", Template("1", "\"{{id}}\"", "desc", parameterInfos), Map("id" -> RawParameterValue("Heinz")))
+        Instance("1", Template("1", "\"{{id}}\"", "desc", "#doc-url", parameterInfos), Map("id" -> RawParameterValue("Heinz")))
       val instance2 =
-        Instance("1", Template("1", "\"{{id}}\"", "desc", parameterInfos), Map("id" -> RawParameterValue("Heinz")))
+        Instance("1", Template("1", "\"{{id}}\"", "desc", "#doc-url",parameterInfos), Map("id" -> RawParameterValue("Heinz")))
       instance1 === instance2
     }
 
     "throw an exception during construction if not all variables are specified in the template's parameter infos" in {
-      Instance("1", Template("1", "\"{{id}}\"", "desc", Map.empty), Map("id" -> RawParameterValue("Heinz"))) must throwA(
+      Instance("1", Template("1", "\"{{id}}\"", "desc", "#doc-url",Map.empty), Map("id" -> RawParameterValue("Heinz"))) must throwA(
         new IllegalArgumentException(
           "requirement failed: The given parameters values (Set(id)) need to match the ones in the template (Set()) (instance id 1)."))
     }

server/src/test/scala/de/frosner/broccoli/models/InstanceWithStatusSpec.scala

@@ -19,6 +19,7 @@ class InstanceWithStatusSpec extends Specification with ScalaCheck with ModelArb
             id = "t",
             template = "{{id}} {{password}}",
             description = "d",
+            documentation_url = "#link-to-documentation",
             parameterInfos = Map(
               "id" -> ParameterInfo("id", None, None, None, ParameterType.Raw, None),
               "password" -> ParameterInfo(
@@ -47,6 +48,7 @@ class InstanceWithStatusSpec extends Specification with ScalaCheck with ModelArb
             id = "t",
             template = "{{id}} {{password}}",
             description = "d",
+            documentation_url = "#link-to-documentation",
             parameterInfos = Map(
               "id" -> ParameterInfo("id", None, None, None, ParameterType.Raw, None),
               "password" -> ParameterInfo(
@@ -79,6 +81,7 @@ class InstanceWithStatusSpec extends Specification with ScalaCheck with ModelArb
             id = "t",
             template = "{{id}} {{password}}",
             description = "d",
+            documentation_url = "#link-to-documentation",
             parameterInfos = Map(
               "id" -> ParameterInfo("id", None, None, None, ParameterType.Raw, None),
               "password" -> ParameterInfo(
@@ -115,6 +118,7 @@ class InstanceWithStatusSpec extends Specification with ScalaCheck with ModelArb
             id = "t",
             template = "{{id}} {{password}}",
             description = "d",
+            documentation_url = "#link-to-documentation",
             parameterInfos = Map(
               "password" -> ParameterInfo(
                 id = "secret password",

server/src/test/scala/de/frosner/broccoli/models/ModelArbitraries.scala

@@ -66,13 +66,15 @@ trait ModelArbitraries {
     for {
       templateId <- Gen.identifier.label("id")
       templateDescription <- Gen.identifier.label("description")
+      templateDocURL <- Gen.identifier.label("documentation_url")
       templateParameters <- Gen.listOf(arbParameterInfo.arbitrary).label("parameterInfos")
     } yield {
       val idParameter = ParameterInfo(id = "id", None, None, None, ParameterType.String, None)
       val template = templateParameters.map(i => s"{{${i.id}}}").mkString(" ")
       Template(
         id = templateId,
         description = templateDescription,
+        documentation_url = templateDocURL,
         // Templates require an "id" parameter so add one here
         template = s"{{id}} $template",
         parameterInfos = templateParameters.map(i => i.id -> i).toMap + ("id" -> idParameter)

server/src/test/scala/de/frosner/broccoli/models/TemplateSpec.scala

@@ -15,21 +15,23 @@ class TemplateSpec extends Specification {
       Template("test",
                "Hallo {{id}}. I like {{person_name}}.",
                "desc",
+               "#link-to-docs",
                Map("id" -> ParameterInfo("id", None, None, None, ParameterType.Raw, None))).parameters === Set("id")
     }
 
     "not automatically extract parameters from a template" in {
-      Template("test", "Hallo {{id}}, how is {{object}}", "desc", Map.empty).parameters === Set.empty
+      Template("test", "Hallo {{id}}, how is {{object}}", "desc", "#link-to-docs", Map.empty).parameters === Set.empty
     }
 
     "create the template version correctly in" in {
-      Template("test", "template JSON", "desc", Map.empty).version === "889df4c8118c30a28ed4f51674a0f19d"
+      Template("test", "template JSON", "desc", "#link-to-docs", Map.empty).version === "889df4c8118c30a28ed4f51674a0f19d"
     }
 
     "result in different template versions if the template JSON differs" in {
-      Template("test", "template JSON", "desc", Map.empty).version !== Template("test",
+      Template("test", "template JSON", "desc", "#link-to-docs", Map.empty).version !== Template("test",
                                                                                 "template JSONs",
                                                                                 "desc",
+                                                                                "#link-to-docs",
                                                                                 Map.empty).version
     }
 
@@ -38,11 +40,13 @@ class TemplateSpec extends Specification {
         id = "test",
         template = "template JSON {{id}}",
         description = "desc",
+        documentation_url = "#link-to-documentation",
         parameterInfos = Map.empty
       ).version !== Template(
         id = "test",
         template = "template JSON {{id}}",
         description = "desc",
+        documentation_url = "#link-to-documentation",
         parameterInfos = Map(
           "id" -> ParameterInfo("id",
                                 None,
@@ -59,7 +63,7 @@ class TemplateSpec extends Specification {
   "Template serialization" should {
 
     "work correctly" in {
-      val originalTemplate = Template("test", "Hallo {{name}}", "desc", Map.empty)
+      val originalTemplate = Template("test", "Hallo {{name}}", "desc", "#docs_url", Map.empty)
       val bos = new ByteArrayOutputStream()
       val oos = new ObjectOutputStream(bos)
       oos.writeObject(originalTemplate)
@@ -81,6 +85,7 @@ class TemplateSpec extends Specification {
         id = "t",
         template = "{{id}}",
         description = "d",
+        documentation_url = "#link-to-documentation",
         parameterInfos = Map.empty
       )
       Json