95 update website documentation for viash 090

_includes/_clone_template.qmd

@@ -2,7 +2,7 @@
 ```{r setup, include=FALSE}
 repo_path <- system("git rev-parse --show-toplevel", intern = TRUE)
 proj_dir <- paste0(repo_path, "/guide/_viash_project_template")
-branch <- "v0.2"
+branch <- "v0.3.0"
 if (!dir.exists(proj_dir)) {
  processx::run(
  "git",

_includes/_r_helper.R

@@ -68,9 +68,15 @@ run_quarto <- function(src_qmd, wdir, engine = "knitr") {
  "render", file_qmd,
  "--to", "markdown",
  "--output", "-"
- )
+ ),
+ echo=FALSE,
+ error_on_status = FALSE
  )
 
+ if (out$status != 0) {
+ stop(out$stderr)
+ }
+
  # strip header
  paste0(out$stdout, "\n") %>%
  paste(collapse = "") %>%

_src/component_examples/example_bash/config.vsh.yaml

@@ -1,21 +1,22 @@
-functionality:
- name: example_bash
- description: A minimal example component.
- arguments:
- - type: file
- name: --input
- example: file.txt
- required: true
- - type: file
- name: --output
- direction: output
- example: output.txt
- required: true
- resources:
- - type: bash_script
- path: script.sh
-platforms:
+name: example_bash
+description: A minimal example component.
+arguments:
+ - type: file
+ name: --input
+ example: file.txt
+ required: true
+ - type: file
+ name: --output
+ direction: output
+ example: output.txt
+ required: true
+resources:
+ - type: bash_script
+ path: script.sh
+engines:
  - type: docker
  image: "bash:4.0"
  - type: native
+runners:
+ - type: executable
  - type: nextflow

_src/component_examples/example_csharp/config.vsh.yaml

@@ -1,21 +1,22 @@
-functionality:
- name: example_csharp
- description: A minimal example component.
- arguments:
- - type: file
- name: --input
- example: file.txt
- required: true
- - type: file
- name: --output
- direction: output
- example: output.txt
- required: true
- resources:
- - type: csharp_script
- path: script.csx
-platforms:
+name: example_csharp
+description: A minimal example component.
+arguments:
+ - type: file
+ name: --input
+ example: file.txt
+ required: true
+ - type: file
+ name: --output
+ direction: output
+ example: output.txt
+ required: true
+resources:
+ - type: csharp_script
+ path: script.csx
+engines:
  - type: docker
  image: "ghcr.io/data-intuitive/dotnet-script:1.3.1"
  - type: native
+runners:
+ - type: executable
  - type: nextflow

_src/component_examples/example_js/config.vsh.yaml

@@ -1,21 +1,22 @@
-functionality:
- name: example_js
- description: A minimal example component.
- arguments:
- - type: file
- name: --input
- example: file.txt
- required: true
- - type: file
- name: --output
- direction: output
- example: output.txt
- required: true
- resources:
- - type: javascript_script
- path: script.js
-platforms:
+name: example_js
+description: A minimal example component.
+arguments:
+ - type: file
+ name: --input
+ example: file.txt
+ required: true
+ - type: file
+ name: --output
+ direction: output
+ example: output.txt
+ required: true
+resources:
+ - type: javascript_script
+ path: script.js
+engines:
  - type: docker
  image: "node:19-bullseye-slim"
  - type: native
+runners:
+ - type: executable
  - type: nextflow

_src/component_examples/example_python/config.vsh.yaml

@@ -1,21 +1,22 @@
-functionality:
- name: example_python
- description: A minimal example component.
- arguments:
- - type: file
- name: --input
- example: file.txt
- required: true
- - type: file
- name: --output
- direction: output
- example: output.txt
- required: true
- resources:
- - type: python_script
- path: script.py
-platforms:
+name: example_python
+description: A minimal example component.
+arguments:
+ - type: file
+ name: --input
+ example: file.txt
+ required: true
+ - type: file
+ name: --output
+ direction: output
+ example: output.txt
+ required: true
+resources:
+ - type: python_script
+ path: script.py
+engines:
  - type: docker
  image: "python:3.10-slim"
  - type: native
+runners:
+ - type: executable
  - type: nextflow

_src/component_examples/example_r/config.vsh.yaml

@@ -1,21 +1,22 @@
-functionality:
- name: example_r
- description: A minimal example component.
- arguments:
- - type: file
- name: --input
- example: file.txt
- required: true
- - type: file
- name: --output
- direction: output
- example: output.txt
- required: true
- resources:
- - type: r_script
- path: script.R
-platforms:
+name: example_r
+description: A minimal example component.
+arguments:
+ - type: file
+ name: --input
+ example: file.txt
+ required: true
+ - type: file
+ name: --output
+ direction: output
+ example: output.txt
+ required: true
+resources:
+ - type: r_script
+ path: script.R
+engines:
  - type: docker
  image: "eddelbuettel/r2u:22.04"
  - type: native
+runners:
+ - type: executable
  - type: nextflow

_src/component_examples/example_scala/config.vsh.yaml

@@ -1,21 +1,22 @@
-functionality:
- name: example_scala
- description: A minimal example component.
- arguments:
- - type: file
- name: --input
- example: file.txt
- required: true
- - type: file
- name: --output
- direction: output
- example: output.txt
- required: true
- resources:
- - type: scala_script
- path: script.scala
-platforms:
+name: example_scala
+description: A minimal example component.
+arguments:
+ - type: file
+ name: --input
+ example: file.txt
+ required: true
+ - type: file
+ name: --output
+ direction: output
+ example: output.txt
+ required: true
+resources:
+ - type: scala_script
+ path: script.scala
+engines:
  - type: docker
  image: "sbtscala/scala-sbt:eclipse-temurin-19_36_1.7.2_2.13.10"
  - type: native
+runners:
+ - type: executable
  - type: nextflow

guide/component/add-dependencies.qmd

@@ -18,13 +18,13 @@ on.exit(unlink(temp_dir, recursive = TRUE), add = TRUE)
 # create tempdir with modified files
 add_setup <- function(...) {
  function(config) {
- config$functionality$name <-
- paste0(config$functionality$name, "_with_setup")
- config$platforms <- map(config$platforms, function(platform) {
- if (platform$type == "docker") {
- platform$setup <- list(...)
+ config$name <-
+ paste0(config$name, "_with_setup")
+ config$engines <- map(config$engines, function(engine) {
+ if (engine$type == "docker") {
+ engine$setup <- list(...)
  }
- platform
+ engine
  })
  config
  }
@@ -104,7 +104,7 @@ for (i in seq_len(nrow(langs))) {
  |Build the executable:
  |
  |```{bash}
- |viash build config.vsh.yaml --platform docker --output target
+ |viash build config.vsh.yaml --engine docker --output target
  |```
  |
  |Build the Docker image:
@@ -129,7 +129,7 @@ pwalk(langs, function(id, label, config_path, script_path, ...) {
  "## {% label %}
  |
  |```bash
- |viash build config.vsh.yaml --platform docker --output target --setup cachedbuild
+ |viash build config.vsh.yaml --engine docker --output target --setup cachedbuild
  |```
  |", 
  .dir = paste0(temp_dir, "/", id)
@@ -138,9 +138,9 @@ pwalk(langs, function(id, label, config_path, script_path, ...) {
 ```
 :::
 
-## Steps for creating a custom Docker platform
+## Steps for creating a custom Docker engine
 
-Here is a series of steps you can follow to add a Docker platform to your Viash component from scratch.
+Here is a series of steps you can follow to add a Docker engine to your Viash component from scratch.
 
 ### Step 1: Choose a base image
 
@@ -242,7 +242,7 @@ pwalk(langs, function(id, label, config_path, script_path, ...) {
  |
  |```bash
  |viash build config.vsh.yaml \
- | --platform docker \
+ | --engine docker \
  | --output target \
  | --setup cachedbuild
  |```
@@ -348,7 +348,7 @@ There are multiple ways you might try to find a Docker image which contains the
 ## Behind the scenes
 
 ### Auto-mount
-Any executable built by Viash with a Docker platform will automatically mount the directories of files passed to the executable as arguments. For example, when running:
+Any executable built by Viash with a Docker engine will automatically mount the directories of files passed to the executable as arguments. For example, when running:
 
 ```bash
 ./my_executable --input /foo/bar/file.txt --output /dest/path

guide/component/add-resources.qmd

@@ -22,8 +22,8 @@ on.exit(unlink(temp_dir, recursive = TRUE), add = TRUE)
 
 # create tempdir with modified files
 add_text_resource <- function(config) {
- config$functionality$resources <- c(
- config$functionality$resources, 
+ config$resources <- c(
+ config$resources, 
  list(list(path = "my_file.txt"))
  )
  config

guide/component/create-component.qmd

@@ -33,9 +33,9 @@ pwalk(langs, function(id, label, example_config, example_script, config_path, sc
 A Viash component can be translated into one or more engines: Native, Docker; and one or more runners: Executable, Nextflow. Each of these engines and runners result in a different artifact:
 
 * [Native engine](/reference/config/engines/native/#): a single executable is generated which runs natively on the host system. This assumes all dependencies are already installed by the user and is therefore not reproducible. Requirements: Bash.
-* [Docker engine](/reference/config/engines/docker/#): a single executable is generated but it runs inside a Docker container instead. The Docker platform specification can help you install custom dependencies and will take care of auto-mounting input/output files. Requirements: Bash, Docker.
+* [Docker engine](/reference/config/engines/docker/#): a single executable is generated but it runs inside a Docker container instead. The Docker engine specification can help you install custom dependencies and will take care of auto-mounting input/output files. Requirements: Bash, Docker.
 
-* [Executable runner](/reference/config/runners/executable/#): 
+* [Executable runner](/reference/config/runners/executable/#): a bash script is generated and can be run directly. The executable runner supports both the native and docker engine.
 * [Nextflow runner](/reference/config/runners/nextflow/#): a Nextflow module which can be used as a standalone workflow or as a module in a larger workflow. Requirements: Nextflow and a containerization engine (e.g. Docker, Singularity, Podman).
 
 Below we will create our first Viash component using any of the languages natively supported by Viash. 
@@ -71,7 +71,7 @@ The `par` variable(s) appear to be hard coded, but they're not! When running thi
 
 ## Create a config
 
-A [Viash config file](/reference/config/#) is a YAML file that describes the functionality of a component and the platform(s) it targets.
+A [Viash config file](/reference/config/#) is a YAML file that describes the functionality of a component as well as the engine(s) and runner(s) it targets.
 
 ::: {.panel-tabset}
 
@@ -93,12 +93,12 @@ pwalk(langs, function(id, label, example_config, ...) {
 
 Here's a breakdown of the different sections:
 
-* `functionality`: A description of what the component does.
- - `name`: The name of the component.
- - `arguments`: The input and output parameters of the script.
- - `resources`: References to all necessary files and folders to make the component work.
-* `platforms`: Lists which platforms a component can target (i.e. Native, Docker or Nextflow).
-
+* `name`: The name of the component.
+* `description`: A description of what the component does
+* `arguments`: The input and output parameters of the script.
+* `resources`: References to all necessary files and folders to make the component work.
+* `engines`: Lists which engines a component can target (i.e. Native or Docker).
+* `runners`: Lists which runners a component can utilize (i.e. Executable or Nextflow).
 
 ## Run the component
 

guide/component/unit-testing.qmd

@@ -32,7 +32,7 @@ on.exit(unlink(temp_dir, recursive = TRUE), add = TRUE)
 # create tempdir with modified files
 add_unit_test <- function(config, type, path) {
  # add helper to resources
- config$functionality$test_resources <- list(
+ config$test_resources <- list(
  list(type = type, path = path)
  )
  config