diff --git a/README.md b/README.md index a4a70f0b..dd61974b 100644 --- a/README.md +++ b/README.md @@ -9,13 +9,13 @@ > [!IMPORTANT] > nf-schema is the new version of the now deprecated [nf-validation](https://github.com/nextflow-io/nf-validation). Please follow the [migration guide](https://nextflow-io.github.io/nf-schema/latest/migration_guide/) to migrate your code to this new version. -This [Nextflow plugin](https://www.nextflow.io/docs/latest/plugins.html#plugins) provides a number of functions that can be included into a Nextflow pipeline script to work with parameter and sample sheet schema. Using these functions you can: +This [Nextflow plugin](https://www.nextflow.io/docs/latest/plugins.html#plugins) provides functionality that can be used in a Nextflow pipeline to work with parameter and sample sheet schema. The added functionality is: - 📖 Print usage instructions to the terminal (for use with `--help`) - ✍️ Print log output showing parameters with non-default values - ✅ Validate supplied parameters against the pipeline schema - 📋 Validate the contents of supplied sample sheet files -- 🛠️ Create a Nextflow channel with a parsed sample sheet +- 🛠️ Create a type-casted list from a parsed sample sheet Supported sample sheet formats are CSV, TSV, JSON and YAML. @@ -25,27 +25,21 @@ Declare the plugin in your Nextflow pipeline configuration file: ```groovy title="nextflow.config" plugins { - id 'nf-schema@2.0.0' + id 'nf-schema@2.1.0' } ``` This is all that is needed - Nextflow will automatically fetch the plugin code at run time. > [!NOTE] -> The snippet above will always try to install the latest version, good to make sure -> that the latest bug fixes are included! However, this can cause difficulties if running -> offline. You can pin a specific release using the syntax `nf-schema@2.0.0` +> The snippet above will always try to install the specified version. We encourage always pinning the +> plugin version to make sure the used pipeline will keep working when a new version of `nf-schema` +> with breaking changes has been released. You can now include the plugin helper functions into your Nextflow pipeline: ```groovy title="main.nf" -include { validateParameters; paramsHelp; paramsSummaryLog; samplesheetToList } from 'plugin/nf-schema' - -// Print help message, supply typical command line usage for the pipeline -if (params.help) { - log.info paramsHelp("nextflow run my_pipeline --input input_file.csv") - exit 0 -} +include { validateParameters; paramsSummaryLog; samplesheetToList } from 'plugin/nf-schema' // Validate input parameters validateParameters() @@ -57,10 +51,21 @@ log.info paramsSummaryLog(workflow) ch_input = Channel.fromList(samplesheetToList(params.input, "assets/schema_input.json")) ``` +Or enable the creation of the help message (using `--help`) in the configuration file: + +```groovy title="nextflow.config" +validation { + help { + enabled: true + } +} +``` + ## Dependencies - Java 11 or later - +- Nextflow 23.10.0 or later ## Slack channel diff --git a/docs/background.md b/docs/background.md index 95dc61bf..444598b3 100644 --- a/docs/background.md +++ b/docs/background.md @@ -1,6 +1,6 @@ --- title: Background -description: Get up and running with nf-schema +description: Background information about nf-schema hide: - toc --- diff --git a/docs/configuration/configuration.md b/docs/configuration/configuration.md index 95a42422..e052a9da 100644 --- a/docs/configuration/configuration.md +++ b/docs/configuration/configuration.md @@ -20,6 +20,16 @@ validation { } ``` +## parametersSchema + +This option can be used to set the parameters JSON schema to be used by the plugin. This will affect parameter validation (`validateParameters()`), the summary logs (`paramsSummaryLog()` and `paramsSummaryMap()`) and the creation of the help messages. + +```groovy +validation.parametersSchema = "path/to/schema.json" // default "nextflow_schema.json" +``` + +This option can either be a path relative to the root of the pipeline directory or a full path to the JSON schema (Be wary to not use hardcoded local paths to ensure your pipeline will keep working on other systems) + ## monochromeLogs This option can be used to turn of the colored logs from nf-validation. This can be useful if you run a Nextflow pipeline in an environment that doesn't support colored logging. @@ -46,7 +56,11 @@ validation.failUnrecognisedParams = // default: false ## showHiddenParams -By default the parameters, that have the `"hidden": true` annotation in the JSON schema, will not be shown in the help message created by `paramsHelp()`. Turning on this option will make sure the hidden parameters are also shown. +!!! deprecated + + This configuration option has been deprecated since v2.1.0. Please use `validation.help.showHidden` instead. + +By default the parameters, that have the `"hidden": true` annotation in the JSON schema, will not be shown in the help message. Turning on this option will make sure the hidden parameters are also shown. ```groovy validation.showHiddenParams = // default: false @@ -71,3 +85,93 @@ This option does exactly the same as `validation.ignoreParams`, but provides pip ```groovy validation.defaultIgnoreParams = ["param1", "param2"] // default: [] ``` + +## help + +The `validation.help` config scope can be used to configure the creation of the help message. + +This scope contains the following options: + +### enabled + +This option is used to enable the creation of the help message when the help parameters are used in the `nextflow run` command. + +```groovy +validation.help.enabled = true // default: false +``` + +### shortParameter + +This option can be used to change the `--help` parameter to another parameter. This parameter will print out the help message with all top level parameters. + +```groovy +validation.help.shortParameter = "giveMeHelp" // default: "help" +``` + +`--giveMeHelp` will now display the help message instead of `--help` for this example. This parameter will print out the help message. + +### fullParameter + +This option can be used to change the `--helpFull` parameter to another parameter. + +```groovy +validation.help.shortParameter = "giveMeHelpFull" // default: "helpFull" +``` + +`--giveMeHelpFull` will now display the expanded help message instead of `--helpFull` for this example. + +### showHiddenParameter + +This option can be used to change the `--showHidden` parameter to another parameter. This parameter tells the plugin to also include the hidden parameters into the help message. + +```groovy +validation.help.showHiddenParameter = "showMeThoseHiddenParams" // default: "showHidden" +``` + +`--showMeThoseHiddenParams ` will now make sure hidden parameters will be shown instead of `--showHidden` for this example. + +### showHidden + +By default the parameters, that have the `"hidden": true` annotation in the JSON schema, will not be shown in the help message. Turning on this option will make sure the hidden parameters are also shown. + +```groovy +validation.help.showHidden = // default: false +``` + +### beforeText + +!!! example "This option does not affect the help message created by the `paramsHelp()` function" + +Any string provided to this option will printed before the help message. + +```groovy +validation.help.beforeText = "Running pipeline version 1.0" // default: "" +``` + +### command + +!!! example "This option does not affect the help message created by the `paramsHelp()` function" + +This option can be used to add an example command to the help message. This will be printed after the `beforeText` and before the help message. + +```groovy +validation.help.command = "nextflow run main.nf --input samplesheet.csv --outdir output" // default: "" +``` + +This example will print the following message: + +```bash +Typical pipeline command: + + nextflow run main.nf --input samplesheet.csv --outdir output +``` + +### afterText + +!!! example "This option does not affect the help message created by the `paramsHelp()` function" + +Any string provided to this option will be printed after the help message. + +```groovy +validation.help.afterText = "Please cite the pipeline owners when using this pipeline" // default: "" +``` diff --git a/docs/contributing/setup.md b/docs/contributing/setup.md index 0f283337..5b5cd1c9 100644 --- a/docs/contributing/setup.md +++ b/docs/contributing/setup.md @@ -13,30 +13,54 @@ To compile and run the tests use the following command: ./gradlew check ``` -## Launch it with Nextflow +## Launch it with installed Nextflow -To test with Nextflow for development purpose: +!!! warning -Clone the Nextflow repo into a sibling directory + This method will add the development version of the plugin to your Nextflow plugins + Take care when using this method and make sure that you are never using a + development version to run real pipelines. + You can delete all `nf-schema` versions using this command: + ```bash + rm -rf ~/.nextflow/plugins/nf-schema* + ``` + +- Install the current version of the plugin in your `.nextflow/plugins` folder + +```bash +make install +``` + +- Update or add the nf-schema plugin with the installed version in your test pipeline + +```groovy title="nextflow.config" +plugins { + id 'nf-schema@x.y.z' +} +``` + +## Launch it with a local version of Nextflow + +- Clone the Nextflow repo into a sibling directory ```bash cd .. && git clone https://github.com/nextflow-io/nextflow cd nextflow && ./gradlew exportClasspath ``` -Append to the `settings.gradle` in this project the following line: +- Append to the `settings.gradle` in this project the following line: ```bash includeBuild('../nextflow') ``` -Compile the plugin code +- Compile the plugin code ```bash ./gradlew compileGroovy ``` -Run nextflow with this command: +- Run nextflow with this command: ```bash ./launch.sh run -plugins nf-schema