Merge pull request #141 from nextflow-io/update/examples

Update nf-schema examples

Author: nvnieuwk

.github/workflows/build.yml

@@ -51,4 +51,4 @@ jobs:
         with:
           name: test-reports-jdk-${{ matrix.java_version }}
           path: |
-            ./plugins/nf-schema/build/reports/tests/test/**
+            ./plugins/nf-schema/build/reports/tests/test/**

.github/workflows/examples.yml

@@ -0,0 +1,36 @@
+name: Check examples
+on:
+  push:
+    tags-ignore:
+      - '*'
+  pull_request:
+jobs:
+  check_examples:
+    name: Check examples output
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 1
+          submodules: true
+
+      - name: Setup Java 21
+        uses: actions/setup-java@v3
+        with:
+          java-version: 21
+          distribution: 'adopt'
+          architecture: x64
+          cache: gradle
+
+      - name: Setup Nextflow
+        uses: nf-core/setup-nextflow@v2
+        with:
+          version: "latest-stable"
+
+      - name: Install nf-schema
+        run: make install
+
+      - name: Check examples
+        run: bash examples/check_examples.sh

CHANGELOG.md

@@ -14,7 +14,8 @@
 3. Rework the deprecated `paramsHelp()` function to allow pipeline developers a fully fledged alternative to the help messages created via the configuration options. This change enables the use of dynamic help message with the strict configuration syntax introduced in Nextflow 25.04.0.
 4. Updated the error message when the JSON schema file is invalid to include the full file name.
 5. The ANSI log setting of Nextflow is now used to determine whether or not the log should be monochrome. This setting will take priority over the `validation.monochromeLogs` configuration option.
-6. Refactored logic for parsing the `jsonschema` validation result into a new `ValidationResult` class.
+6. Updated the examples in the [examples](examples/) directory and added automatic checking for validity of these examples.
+7. Refactored logic for parsing the `jsonschema` validation result into a new `ValidationResult` class.
 
 ## Bug fixes
 

docs/nextflow_schema/nextflow_schema_examples.md

@@ -18,3 +18,5 @@ It is used as a test fixture in the nf-schema package [here](https://github.com/
 ```json
 --8<-- "src/testResources/nextflow_schema.json"
 ```
+
+Even more examples can be found in the plugin [`examples` directory](../../examples) in the GitHub repository.

docs/nextflow_schema/sample_sheet_schema_examples.md

@@ -9,15 +9,6 @@ description: Example JSON Schema for a Nextflow pipeline `nextflow_schema.json`
 The nf-core/rnaseq pipeline was one of the first to have a sample sheet schema.
 You can see this, used for validating sample sheets with `--input` here: [`assets/schema_input.json`](https://github.com/nf-core/rnaseq/blob/5671b65af97fe78a2f9b4d05d850304918b1b86e/assets/schema_input.json).
 
-!!! tip
-
-    Note the approach used for validating filenames in the `fastq_2` column.
-    The column is optional, so if a `pattern` was supplied by itself then validation would fail
-    when no string is supplied.
-
-    Instead, we say that the string must _either_ match that pattern or it must have a
-    `maxLength` of `0` (an empty string).
-
 ```json
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
@@ -71,3 +62,5 @@ It is used as a test fixture in the nf-schema package [here](https://github.com/
 ```json
 --8<-- "src/testResources/schema_input.json"
 ```
+
+Even more examples can be found in the plugin [`examples` directory](../../examples) in the GitHub repository.

examples/README.md

@@ -0,0 +1,13 @@
+# nf-schema examples
+
+This directory contains example files for the nf-schema project.
+
+1. [Help Message](./helpMessage/) contains a pipeline that generates a help message for a given schema.
+2. [Parameter summary log](./paramSummaryLog/) contains a pipeline that generates a summary log of the parameters used in a given schema.
+3. [Parameter summary map](./paramSummaryMap/) contains a pipeline that generates a summary map of the parameters used in a given schema. The difference between with the previous example is that this one produces a machine readable data structure instead of a human readable output string.
+4. [Basic samplesheet conversion](./samplesheetToListBasic/) contains a pipeline that converts a samplesheet to a list that can be easily converted to a channel for usage in the pipeline.
+5. [Samplesheet conversion with meta](./samplesheetToListMeta/) contains a pipeline that converts a samplesheet to a list that can be easily converted to a channel for usage in the pipeline. This example contains a meta map.
+6. [Samplesheet conversion order](./samplesheetToListOrder/) contains a pipeline that converts a samplesheet to a list. This example is used to explain the order of the fields in the samplesheet can be changed freely while maintaining the same output list order. The output order is based on the order of the fields in the schema.
+7. [Validate Parameters](./validateParameters/) contains a pipeline that validates the parameters used in a given schema.
+8. [Fail unrecognized parameters](./failUnrecognizedParameters/) contains a pipeline that fails when unrecognized parameters are used in a given schema.
+9. [Warning unrecognized parameters](./warningUnrecognizedParameters/) contains a pipeline that warns when unrecognized parameters are used in a given schema.

examples/check_examples.sh

@@ -0,0 +1,47 @@
+script_dir=$(dirname "$0")
+plugin_version=$(grep 'version =' "$script_dir/../build.gradle" | awk -F "'" '{print $2}')
+
+echo "Testing examples with nf-schema version $plugin_version"
+
+failures=0
+ignore_values='runName|launchDir|workDir|Check script|projectDir|userName|configFiles'
+
+run_example() {
+    echo "Running example command: $command"
+    output=$(eval $command 2>&1 | tail -n +5 | grep -vE "$ignore_values")
+
+    expected_text=$(cat $expected_output | tail -n +5 | grep -vE "$ignore_values")
+
+    echo "Comparing with expected output: $expected_output"
+    if [ "$output" == "$expected_text" ]; then
+        echo "Test passed!"
+    else
+        failures=$((failures + 1))
+        echo "Test failed!"
+        diff <(echo "$output") <(echo "$expected_text")
+    fi
+}
+
+for example in $script_dir/*/pipeline/main.nf
+do
+    example_dir=$(dirname "$example")
+    if compgen -G "$example_dir/../options*.txt" > /dev/null; then
+        for option in $example_dir/../options*.txt
+        do
+            command="COLUMNS=1000 nextflow run $example -plugins nf-schema@$plugin_version $(cat $option)"
+            expected_output=$(echo $option | sed -e 's/options/log/')
+            run_example
+        done
+    else
+        command="COLUMNS=1000 nextflow run $example -plugins nf-schema@$plugin_version"
+        expected_output="$(dirname $example)/../log.txt"
+        run_example
+    fi
+done
+
+if [ $failures -eq 0 ]; then
+    echo "All tests passed!"
+else
+    echo "$failures test(s) failed."
+    exit 1
+fi

examples/helpMessage/README.md

@@ -0,0 +1,7 @@
+# Help Message
+
+This example demonstrates how to generate a help message for a given schema using the nf-schema plugin.
+
+There are two example log files provided in this directory:
+- `log.txt`: This log file shows the output when running the pipeline with the `--help` option. It contains the help message generated for the schema.
+- `log_outdir.txt`: This log file shows the output when running the pipeline with the `--help outdir` option. It contains the help message for the `outdir` parameter specifically.

examples/helpMessage/log.txt

@@ -0,0 +1,26 @@
+
+ N E X T F L O W   ~  version 25.04.6
+
+Launching `examples/helpMessage/pipeline/main.nf` [nauseous_hoover] DSL2 - revision: 629cc11c05
+
+
+This is a help message for the pipeline.
+It provides information about the parameters and usage.
+
+    Typical pipeline command:
+
+  nextflow run my_pipeline --input input_file.csv
+
+--help         [boolean, string] Show the help message for all top level parameters. When a parameter is given to `--help`, the full help message of that parameter will be printed. 
+--helpFull     [boolean]         Show the help message for all non-hidden parameters. 
+--showHidden   [boolean]         Show all hidden parameters in the help message. This needs to be used in combination with `--help` or `--helpFull`. 
+
+Input/output options
+  --input      [string]  Path to comma-separated file containing information about the samples in the experiment. 
+  --outdir     [string]  The output directory where the results will be saved. You have to use absolute paths to storage on Cloud infrastructure. 
+  --help       [boolean] Show the help message for the pipeline. [default: false] 
+
+------------------------------------------------------
+
+For more information, please refer to the documentation.
+    

examples/helpMessage/log_outdir.txt

@@ -0,0 +1,21 @@
+
+ N E X T F L O W   ~  version 25.04.6
+
+Launching `examples/helpMessage/pipeline/main.nf` [fabulous_boyd] DSL2 - revision: 629cc11c05
+
+
+This is a help message for the pipeline.
+It provides information about the parameters and usage.
+
+    Typical pipeline command:
+
+  nextflow run my_pipeline --input input_file.csv
+
+--outdir
+    type       : string
+    format     : directory-path
+    description: The output directory where the results will be saved. You have to use absolute paths to storage on Cloud infrastructure.
+------------------------------------------------------
+
+For more information, please refer to the documentation.
+