Add label & summary fields for Config, PackageConfig, argument groups…

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 TODO add summary
 
+## NEW FUNCTIONALITY
+
+* `config schema`: Add `label` & `summary` fields for Config, PackageConfig, argument groups, and all argument types (PR #743).
+
 ## BUG FIXES
 
 * `platforms`: Re-introduce the `--platform` and `--apply_platform` arguments to improve backwards compatibility (PR #725).

src/main/scala/io/viash/ViashTest.scala

@@ -266,7 +266,7 @@ object ViashTest extends Logging {
             namespace = conf.namespace,
             version = conf.version,
             // set dirArg as argument so that Docker can chown it after execution
-            argument_groups = List(ArgumentGroup("default", None, List(dirArg))),
+            argument_groups = List(ArgumentGroup("default", arguments = List(dirArg))),
             resources = List(test),
             set_wd_to_resources_dir = true,
             // Make sure we'll be using the same docker registry set in 'links' so we can have the same docker image id.

src/main/scala/io/viash/config/ArgumentGroup.scala

@@ -25,7 +25,24 @@ case class ArgumentGroup(
   @description("The name of the argument group.")
   name: String,
 
-  @description("Description of foo`, a description of the argument group. Multiline descriptions are supported.")
+  @description("A clean version of the argument group's name. This is only used for documentation.")
+  @example("label: \"My argument group\"", "yaml")
+  @default("Empty")
+  @since("Viash 0.9.0")
+  label: Option[String] = None,
+
+  @description("A one-sentence summary of the argument group. This is only used for documentation.")
+  @example("summary: \"Arguments related to functionality XYZ\"", "yaml")
+  @default("Empty")
+  @since("Viash 0.9.0")
+  summary: Option[String] = None,
+
+  @description("A description of the argument group. This is only used for documentation. Multiline descriptions are supported.")
+  @example(
+    """description: |
+      |  A (multiline) description of the purpose of the arguments
+      |  in this argument group.""".stripMargin, "yaml")
+  @default("Empty")
   description: Option[String] = None,
 
   @description("List of arguments.")

src/main/scala/io/viash/config/Config.scala

@@ -189,7 +189,20 @@ case class Config(
   @default("Empty")
   resources: List[Resource] = Nil,
 
-  @description("A description of the component. This will be displayed with `--help`.")
+  @description("A clean version of the component's name. This is only used for documentation.")
+  @example("label: \"My component\"", "yaml")
+  @default("Empty")
+  @since("Viash 0.9.0")
+  label: Option[String] = None,
+
+  @description("A one-sentence summary of the component. This is only used for documentation.")
+  @example("summary: \"A component for performing XYZ\"", "yaml")
+  @default("Empty")
+  @since("Viash 0.9.0")
+  summary: Option[String] = None,
+
+  @description("A description of the component. This is only used for documentation. Multiline descriptions are supported.")
+  @default("Empty")
   @example(
     """description: |
       +  This component performs function Y and Z.

src/main/scala/io/viash/config/arguments/Argument.scala

@@ -62,6 +62,8 @@ abstract class Argument[Type] {
   val `type`: String
   val name: String
   val alternatives: OneOrMore[String]
+  val label: Option[String]
+  val summary: Option[String]
   val description: Option[String]
   val info: Json
   val example: OneOrMore[Type]
@@ -87,6 +89,8 @@ abstract class Argument[Type] {
     `type`: String = this.`type`,
     name: String = this.name,
     alternatives: OneOrMore[String] = this.alternatives,
+    label: Option[String] = this.label,
+    summary: Option[String] = this.summary,
     description: Option[String] = this.description,
     info: Json = this.info,
     example: OneOrMore[Type] = this.example,

src/main/scala/io/viash/config/arguments/BooleanArgument.scala

@@ -49,8 +49,25 @@ case class BooleanArgument(
   @description("List of alternative format variations for this argument.")
   @default("Empty")
   alternatives: OneOrMore[String] = Nil,
+
+  @description("A clean version of the argument's name. This is only used for documentation.")
+  @example("label: \"My argument\"", "yaml")
+  @default("Empty")
+  @since("Viash 0.9.0")
+  label: Option[String] = None,
 
-  @description("A description of the argument. This will be displayed with `--help`.")
+  @description("A one-sentence summary of the argument. This is only used for documentation.")
+  @example("summary: \"This argument sets XYZ.\"", "yaml")
+  @default("Empty")
+  @since("Viash 0.9.0")
+  summary: Option[String] = None,
+
+  @description("A description of the argument. This is only used for documentation. Multiline descriptions are supported.")
+  @example(
+    """description: |
+      |  A (multiline) description of the purpose of
+      |  this argument.""".stripMargin, "yaml")
+  @default("Empty")
   description: Option[String] = None,
 
   @description("Structured information. Can be any shape: a string, vector, map or even nested map.")
@@ -129,6 +146,8 @@ case class BooleanArgument(
     `type`: String, 
     name: String, 
     alternatives: OneOrMore[String],
+    label: Option[String],
+    summary: Option[String],
     description: Option[String],
     info: Json,
     example: OneOrMore[Boolean],
@@ -139,7 +158,7 @@ case class BooleanArgument(
     multiple_sep: String,
     dest: String
   ): Argument[Boolean] = {
-    copy(name, alternatives, description, info, example, default, required, direction, multiple, multiple_sep, dest, `type`)
+    copy(name, alternatives, label, summary, description, info, example, default, required, direction, multiple, multiple_sep, dest, `type`)
   }
 }
 
@@ -167,7 +186,24 @@ case class BooleanTrueArgument(
   @default("Empty")
   alternatives: OneOrMore[String] = Nil,
 
-  @description("A description of the argument. This will be displayed with `--help`.")
+  @description("A clean version of the argument's name. This is only used for documentation.")
+  @example("label: \"My argument\"", "yaml")
+  @default("Empty")
+  @since("Viash 0.9.0")
+  label: Option[String] = None,
+
+  @description("A one-sentence summary of the argument. This is only used for documentation.")
+  @example("summary: \"This argument sets XYZ.\"", "yaml")
+  @default("Empty")
+  @since("Viash 0.9.0")
+  summary: Option[String] = None,
+
+  @description("A description of the argument. This is only used for documentation. Multiline descriptions are supported.")
+  @example(
+    """description: |
+      |  A (multiline) description of the purpose of
+      |  this argument.""".stripMargin, "yaml")
+  @default("Empty")
   description: Option[String] = None,
 
   @description("Structured information. Can be any shape: a string, vector, map or even nested map.")
@@ -202,6 +238,8 @@ case class BooleanTrueArgument(
     `type`: String, 
     name: String, 
     alternatives: OneOrMore[String],
+    label: Option[String],
+    summary: Option[String],
     description: Option[String],
     info: Json,
     default: OneOrMore[Boolean],
@@ -212,7 +250,7 @@ case class BooleanTrueArgument(
     multiple_sep: String,
     dest: String
   ): Argument[Boolean] = {
-    copy(name, alternatives, description, info, direction, dest, `type`)
+    copy(name, alternatives, label, summary, description, info, direction, dest, `type`)
   }
 }
 
@@ -240,7 +278,24 @@ case class BooleanFalseArgument(
   @default("Empty")
   alternatives: OneOrMore[String] = Nil,
 
-  @description("A description of the argument. This will be displayed with `--help`.")
+  @description("A clean version of the argument's name. This is only used for documentation.")
+  @example("label: \"My argument\"", "yaml")
+  @default("Empty")
+  @since("Viash 0.9.0")
+  label: Option[String] = None,
+
+  @description("A one-sentence summary of the argument. This is only used for documentation.")
+  @example("summary: \"This argument sets XYZ.\"", "yaml")
+  @default("Empty")
+  @since("Viash 0.9.0")
+  summary: Option[String] = None,
+
+  @description("A description of the argument. This is only used for documentation. Multiline descriptions are supported.")
+  @example(
+    """description: |
+      |  A (multiline) description of the purpose of
+      |  this argument.""".stripMargin, "yaml")
+  @default("Empty")
   description: Option[String] = None,
 
   @description("Structured information. Can be any shape: a string, vector, map or even nested map.")
@@ -276,6 +331,8 @@ case class BooleanFalseArgument(
     `type`: String, 
     name: String, 
     alternatives: OneOrMore[String],
+    label: Option[String],
+    summary: Option[String],
     description: Option[String],
     info: Json,
     default: OneOrMore[Boolean],
@@ -286,6 +343,6 @@ case class BooleanFalseArgument(
     multiple_sep: String,
     dest: String
   ): Argument[Boolean] = {
-    copy(name, alternatives, description, info, direction, dest, `type`)
+    copy(name, alternatives, label, summary, description, info, direction, dest, `type`)
   }
 }

src/main/scala/io/viash/config/arguments/DoubleArgument.scala

@@ -46,7 +46,24 @@ case class DoubleArgument(
   @default("Empty")
   alternatives: OneOrMore[String] = Nil,
 
-  @description("A description of the argument. This will be displayed with `--help`.")
+  @description("A clean version of the argument's name. This is only used for documentation.")
+  @example("label: \"My argument\"", "yaml")
+  @default("Empty")
+  @since("Viash 0.9.0")
+  label: Option[String] = None,
+
+  @description("A one-sentence summary of the argument. This is only used for documentation.")
+  @example("summary: \"This argument sets XYZ.\"", "yaml")
+  @default("Empty")
+  @since("Viash 0.9.0")
+  summary: Option[String] = None,
+
+  @description("A description of the argument. This is only used for documentation. Multiline descriptions are supported.")
+  @example(
+    """description: |
+      |  A (multiline) description of the purpose of
+      |  this argument.""".stripMargin, "yaml")
+  @default("Empty")
   description: Option[String] = None,
 
   @description("Structured information. Can be any shape: a string, vector, map or even nested map.")
@@ -139,6 +156,8 @@ case class DoubleArgument(
     `type`: String, 
     name: String, 
     alternatives: OneOrMore[String],
+    label: Option[String],
+    summary: Option[String],
     description: Option[String],
     info: Json,
     example: OneOrMore[Double],
@@ -149,6 +168,6 @@ case class DoubleArgument(
     multiple_sep: String,
     dest: String
   ): Argument[Double] = {
-    copy(name, alternatives, description, info, example, default, required, this.min, this.max, direction, multiple, multiple_sep, dest, `type`)
+    copy(name, alternatives, label, summary, description, info, example, default, required, this.min, this.max, direction, multiple, multiple_sep, dest, `type`)
   }
 }

src/main/scala/io/viash/config/arguments/FileArgument.scala

@@ -47,7 +47,24 @@ case class FileArgument(
   @default("Empty")
   alternatives: OneOrMore[String] = Nil,
 
-  @description("A description of the argument. This will be displayed with `--help`.")
+  @description("A clean version of the argument's name. This is only used for documentation.")
+  @example("label: \"My argument\"", "yaml")
+  @default("Empty")
+  @since("Viash 0.9.0")
+  label: Option[String] = None,
+
+  @description("A one-sentence summary of the argument. This is only used for documentation.")
+  @example("summary: \"This argument sets XYZ.\"", "yaml")
+  @default("Empty")
+  @since("Viash 0.9.0")
+  summary: Option[String] = None,
+
+  @description("A description of the argument. This is only used for documentation. Multiline descriptions are supported.")
+  @example(
+    """description: |
+      |  A (multiline) description of the purpose of
+      |  this argument.""".stripMargin, "yaml")
+  @default("Empty")
   description: Option[String] = None,
 
   @description("Structured information. Can be any shape: a string, vector, map or even nested map.")
@@ -165,6 +182,8 @@ case class FileArgument(
     `type`: String, 
     name: String, 
     alternatives: OneOrMore[String],
+    label: Option[String],
+    summary: Option[String],
     description: Option[String],
     info: Json,
     example: OneOrMore[Path],
@@ -176,7 +195,7 @@ case class FileArgument(
     dest: String
   ): Argument[Path] = {
     copy(
-      name, alternatives, description, info, example, default, 
+      name, alternatives, label, summary, description, info, example, default, 
       this.must_exist, this.create_parent, required, direction, 
       multiple, multiple_sep, dest, `type`
     )

src/main/scala/io/viash/config/arguments/IntegerArgument.scala

@@ -46,7 +46,24 @@ case class IntegerArgument(
   @default("Empty")
   alternatives: OneOrMore[String] = Nil,
 
-  @description("A description of the argument. This will be displayed with `--help`.")
+  @description("A clean version of the argument's name. This is only used for documentation.")
+  @example("label: \"My argument\"", "yaml")
+  @default("Empty")
+  @since("Viash 0.9.0")
+  label: Option[String] = None,
+
+  @description("A one-sentence summary of the argument. This is only used for documentation.")
+  @example("summary: \"This argument sets XYZ.\"", "yaml")
+  @default("Empty")
+  @since("Viash 0.9.0")
+  summary: Option[String] = None,
+
+  @description("A description of the argument. This is only used for documentation. Multiline descriptions are supported.")
+  @example(
+    """description: |
+      |  A (multiline) description of the purpose of
+      |  this argument.""".stripMargin, "yaml")
+  @default("Empty")
   description: Option[String] = None,
 
   @description("Structured information. Can be any shape: a string, vector, map or even nested map.")
@@ -149,6 +166,8 @@ case class IntegerArgument(
     `type`: String, 
     name: String, 
     alternatives: OneOrMore[String],
+    label: Option[String],
+    summary: Option[String],
     description: Option[String],
     info: Json,
     example: OneOrMore[Int],
@@ -159,6 +178,6 @@ case class IntegerArgument(
     multiple_sep: String,
     dest: String
   ): Argument[Int] = {
-    copy(name, alternatives, description, info, example, default, required, this.choices, this.min, this.max, direction, multiple, multiple_sep, dest, `type`)
+    copy(name, alternatives, label, summary, description, info, example, default, required, this.choices, this.min, this.max, direction, multiple, multiple_sep, dest, `type`)
   }
 }

src/main/scala/io/viash/config/arguments/LongArgument.scala

@@ -47,7 +47,24 @@ case class LongArgument(
   @default("Empty")
   alternatives: OneOrMore[String] = Nil,
 
-  @description("A description of the argument. This will be displayed with `--help`.")
+  @description("A clean version of the argument's name. This is only used for documentation.")
+  @example("label: \"My argument\"", "yaml")
+  @default("Empty")
+  @since("Viash 0.9.0")
+  label: Option[String] = None,
+
+  @description("A one-sentence summary of the argument. This is only used for documentation.")
+  @example("summary: \"This argument sets XYZ.\"", "yaml")
+  @default("Empty")
+  @since("Viash 0.9.0")
+  summary: Option[String] = None,
+
+  @description("A description of the argument. This is only used for documentation. Multiline descriptions are supported.")
+  @example(
+    """description: |
+      |  A (multiline) description of the purpose of
+      |  this argument.""".stripMargin, "yaml")
+  @default("Empty")
   description: Option[String] = None,
 
   @description("Structured information. Can be any shape: a string, vector, map or even nested map.")
@@ -150,6 +167,8 @@ case class LongArgument(
     `type`: String, 
     name: String, 
     alternatives: OneOrMore[String],
+    label: Option[String],
+    summary: Option[String],
     description: Option[String],
     info: Json,
     example: OneOrMore[Long],
@@ -160,6 +179,6 @@ case class LongArgument(
     multiple_sep: String,
     dest: String
   ): Argument[Long] = {
-    copy(name, alternatives, description, info, example, default, required, this.choices, this.min, this.max, direction, multiple, multiple_sep, dest, `type`)
+    copy(name, alternatives, label, summary, description, info, example, default, required, this.choices, this.min, this.max, direction, multiple, multiple_sep, dest, `type`)
   }
 }