Allow specifying a short description and a title

[rcannood]

In OpenPipelines the .info field is used to fill in the website:

functionality:
  name: "bd_rhapsody"
  description: |
    One sentence.

    Two sentences.

    Three sentences.
  info:
    name: "BD Rhapsody"
    summary: One sentence.

These fields are also to be used in other applications, so we'll add the following fields to the config:

functionality:
  name: "bd_rhapsody"
  title: "BD Rhapsody"
  summary: One sentence.
  description:
    - One sentence.
    - |
      Two sentences.

      Three sentences.

The defaults and types of these new fields:

title: String = name.replaceAll("_", " ").capitalize()
description: OneOrMore[Either[String, Resource]] = Nil
def getDescription(): List[String] = description.map ( ... )

[rcannood]

Hmmm... case classes can't have defaults which depend on other arguments of the case class.

It would be best if we fill this in in Config.read(...) right before returning the config, e.g.:

val config1 = config0.copy(
  title = Some(config0.title.getOrElse(config0.name.replaceAll("_", " ").capitalize))
)

This means title would be an argument of Functionality as follows:

  @description("A human-readable name for the component. By default, all underscores in `.name` are replaced by spaces and the first letter is capitalised.")
  @example("name: \"This is my component\"", "yaml")
  title: Option[String] = None,

[Grifs]

@rcannood @DriesSchaumont Is this issue still relevant? While I didn't do an exhaustive search through the OpenPipelines repository, I haven't spotted any .functionality.info.name or .functionality.info.description fields.

[DriesSchaumont]

@Grifs Some components in openpipelines still use .functionality.info.name: see viash ns exec 'yq ".functionality.info.name" {abs-path} \;' 2> /dev/null But not sure if we still want this, @rcannood WDYT?

[Grifs]

This topic just came up again, but in this case to have a short description field for arguments ... so if we'd implement this, it might make sense to do so wherever description fields are present and/or make sense.

[rcannood]

@rcannood @DriesSchaumont Is this issue still relevant? While I didn't do an exhaustive search through the OpenPipelines repository, I haven't spotted any .functionality.info.name or .functionality.info.description fields.

Apologies for the late response -- yes!

In the meantime, I'd be inclined to use the following:

name: my_component
label: My component
summary: A one-line summary of my component
description: |
  A longer description of how this component works and
  when and how somebody might want to use it.

arguments:
  - type: --bam
    label: Input BAM file
    summary: A one-line summary of what this argument is
    description: |
      A longer description of what this argument is used for and
      the data format of the data you need to pass to it.

I'm on the fence about the following:

label vs title

I feel title suits a component better, but label suits an argument better. However, I'd use the same name for both labelling the component and the argument.

Whether or not to include a summary

If there is already a label and a description, a summary might feel a bit redundant. However, we do use the [label, summary, description] system in OpenProblems, where label and summary is used to generate overviews of components, and the [label, summary, description] is used to generate detailed documentation page of an individual component. I feel the same could be true for Viash Hub.

[Grifs]

Implemented in Viash 0.9.0