From f564f3cd0d14fc553723449deae5462c18ecea42 Mon Sep 17 00:00:00 2001 From: Nicolas Vannieuwkerke Date: Tue, 13 Aug 2024 17:03:53 +0200 Subject: [PATCH 01/12] update first batch of docs --- README.md | 31 ++++++++++++++++++------------- docs/background.md | 2 +- docs/migration_guide.md | 27 +++++++++++++++++++++++++++ 3 files changed, 46 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index a4a70f0..dd61974 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 95dc61b..444598b 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/migration_guide.md b/docs/migration_guide.md index 31161ae..001bee2 100644 --- a/docs/migration_guide.md +++ b/docs/migration_guide.md @@ -26,6 +26,7 @@ Following list shows the major breaking changes introduced in nf-schema: 3. The `unique` keyword for samplesheet schemas has been removed. Please use [`uniqueItems`](https://json-schema.org/understanding-json-schema/reference/array#uniqueItems) or [`uniqueEntries`](nextflow_schema/nextflow_schema_specification.md#uniqueentries) now instead. 4. The `dependentRequired` keyword now works as it's supposed to work in JSON schema. See [`dependentRequired`](https://json-schema.org/understanding-json-schema/reference/conditionals#dependentRequired) for more information. 5. All configuration parameters have been converted to Nextflow configuration options. See [Updating configuration](#updating-configuration) for more information. +6. Help messages are now created automatically instead of using the `paramsHelp()` function. (v2.1.0 feature) A full list of changes can be found in the [changelog](https://github.com/nextflow-io/nf-schema/blob/master/CHANGELOG.md). @@ -263,3 +264,29 @@ When you use `dependentRequired` in your schemas, you should update it like this } } ``` + +### Updating the help message + +!!! example "v2.1.0 feature" + +The creation of the help message now needs to be enabled in the configuration file. Using `--help` or `--helpFull` will automatically print the help message and stop the pipeline execution. `paramsHelp()` is still available in `nf-schema` and can still be used like before. This could be helpful to print the help message in specific cases. Mind that this function now automatically emits a deprecation warning. This warning can be disabled using the `hideWarning:true` option of the function. + +=== "nf-validation" + + ```groovy title="main.nf" + if (params.help) { + log.info paramsHelp("nextflow run my_pipeline --input input_file.csv") + exit 0 + } + ``` + +=== "nf-schema" + + ```groovy title="nextflow.config" + validation { + help { + enabled: true + command: "nextflow run my_pipeline --input input_file.csv" + } + } + ``` \ No newline at end of file From 4257d5ab13bee4731b98fdae46d9358058101f49 Mon Sep 17 00:00:00 2001 From: Nicolas Vannieuwkerke Date: Wed, 14 Aug 2024 12:43:21 +0200 Subject: [PATCH 02/12] finish help message docs --- docs/configuration/configuration.md | 106 +++++++++++++- docs/parameters/help_text.md | 211 +++++++++++++++++++++++----- 2 files changed, 278 insertions(+), 39 deletions(-) diff --git a/docs/configuration/configuration.md b/docs/configuration/configuration.md index 95a4242..cca8512 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 expanded 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" +``` + +`--showHidden` 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 `paramsHelp()`" + +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 `paramsHelp()`" + +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 `paramsHelp()`" + +Any string provided to this option will printed after the help message. + +```groovy +validation.help.afterText = "Please cite the pipeline owners when using this pipeline" // default: "" +``` diff --git a/docs/parameters/help_text.md b/docs/parameters/help_text.md index 422f8f3..08f3ceb 100644 --- a/docs/parameters/help_text.md +++ b/docs/parameters/help_text.md @@ -1,12 +1,182 @@ +## Configure help message + +Add the following configuration to your configuration files to enable the creation of help messages: + +```groovy title="nextflow.config" +validation { + help { + enabled: true + } +} +``` + +That's it! Every time the pipeline user passes the `--help` and `--helpFull` parameters to the pipeline, the help message will be created! + +The help message can be customized with a series of different options. See [help configuration](../configuration/configuration.md#help) docs for a list of all options. + +## Help message + +Following example shows a snippet of a JSON schema which can be used to perfect visualize the differences between the different help messages. This schema contains one group of parameters called `Input parameters` that contains two parameters: `--input` and `--outdir`. There are also two ungrouped parameters in this schema: `--reference` and `--type`. `--reference` is a nested parameter that contains the `.fasta`, `.fai` and `.aligners` subparameters. `.aligners` also contains two subparameters: `.bwa` and `.bowtie`. + +There are three different help messages: + +1. Using `--help` will only show the top level parameters (`--input`, `--outdir`, `--reference` and `--type` in the example). The type, description, possible options and defaults of these parameters will also be added to the message if they are present in the JSON schema. +2. Using `--helpFull` will print all parameters (no matter how deeply nested they are) (`--input`, `--outdir`, `--reference.fasta`, `--reference.fai`, `--reference.aligners.bwa`, `--reference.aligners.bowtie` and `--type` in the example) +3. `--help` can also be used with a parameter given to it. This will print out a detailed help message of the parameter. This will also show and subparameters present for the parameter. + +=== "JSON schema" + + ```json + ... + "$defs": { // A section to define several definition in the JSON schema + "Input parameters": { // A group called "Input parameters" + "properties": { // All properties (=parameters) in this group + "input": { + "type": "string", + "description": "The input samplesheet", + "format": "file-path", + "pattern": "^.$\.csv$", + "help_text": "This file needs to contain all input samples", + "exists": true + }, + "outdir": { + "type": "string", + "description": "The output directory", + "format": "directory-path", + "default": "results" + } + } + } + }, + "properties": { // Ungrouped parameters go here + "reference": { + "type": "object", // A parameter that contains nested parameters is always an "object" + "description": "A group of parameters to configure the reference sets", + "properties": { // All parameters nested in the --reference parameter + "fasta": { + "type": "string", + "description": "The FASTA file" + }, + "fai": { + "type": "string", + "description": "The FAI file" + }, + "aligners": { + "type": "object", + "description": "A group of parameters specifying the aligner indices", + "properties": { // All parameters nested in the --reference.aligners parameter + "bwa": { + "type": "string", + "description": "The BWA index" + }, + "bowtie": { + "type": "string", + "description": "The BOWTIE index" + } + } + } + } + }, + "type": { + "type": "string", + "description": "The analysis type", + "enum": ["WES","WGS"] + } + } + ... + ``` + +=== "`--help`" + + ```bash + --reference [object] A group of parameters to configure the reference sets + --type [string] The analysis type (accepted: WES, WGS) + --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 parameters + --input [string] The input samplesheet + --outdir [string] The output directory [default: results] + ``` + +=== "`--helpFull`" + + ```bash + --reference.fasta [string] The FASTA file + --reference.fai [string] The FAI file + --reference.aligners.bwa [string] The BWA index + --reference.aligners.bowtie [string] The BOWTIE index + --type [string] The analysis type (accepted: WES, WGS) + --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 parameters + --input [string] The input samplesheet + --outdir [string] The output directory [default: results] + ``` + +=== "`--help input`" + + ```bash + --input + type : string + description: The input samplesheet + format : file-path + pattern : ^.$\.csv$ + help_text : This file needs to contain all input samples + exists : true + ``` + +=== "`--help reference.aligners`" + + ```bash + --reference.aligners + type : object + description: A group of parameters specifying the aligner indices + options : + --reference.aligners.bwa [string] The BWA index + --reference.aligners.bowtie [string] The BOWTIE index + ``` + +The help message will always show the ungrouped parameters first. `--help`, `--helpFull` and `--showHidden` will always be automatically added to the help message. These defaults can be overwritten by adding them as ungrouped parameters to the JSON schema. + +After the ungrouped parameters, the grouped parameters will be printed. + +## Hidden parameters + +Params that are set as `hidden` in the JSON Schema are not shown in the help message. +To show these parameters, pass the `--showHidden` parameter to the nextflow command. + +## Coloured logs + +By default, the help output is coloured using ANSI escape codes. + +If you prefer, you can disable these by setting the `validation.monochromeLogs` configuration option to `true` + +=== "Default (coloured)" + + ![Default help output](../images/help_not_monochrome_logs.png) + +=== "Monochrome logs" + + ![Default help output](../images/help_monochrome_logs.png) + ## `paramsHelp()` +!!! deprecated + + This function has been deprecated in v2.1.0. Use the [help configuration](#configure-help-message) instead + This function returns a help message with the command to run a pipeline and the available parameters. Pass it to `log.info` to print in the terminal. -It accepts two arguments: +It accepts three arguments: 1. An example command, typically used to run the pipeline, to be included in the help string -2. The file name of a Nextflow Schema file (Default: `nextflow_schema.json`) +2. An option to set the file name of a Nextflow Schema file: `parameters_schema: ` (Default: `nextflow_schema.json`) +3. An option to hide the deprecation warning: `hideWarning: ` (Default: `false`) !!! Note @@ -42,39 +212,4 @@ Output: !!! warning We shouldn't be using `exit` as it kills the Nextflow head job in a way that is difficult to handle by systems that may be running it externally, but at the time of writing there is no good alternative. - See [`nextflow-io/nextflow#3984`](https://github.com/nextflow-io/nextflow/issues/3984). - -## Specific parameter help - -By default, when printing the help message only a selection of attributes are printed: type of the variable, accepted options (enums), description and default value. - -To print the complete information for a single parameter, pass the parameter name to the `--help` option. - -For example, with the example above: - -```bash -nextflow run my_pipeline --help outdir -``` - -``` ---8<-- "examples/paramsHelp/log_outdir.txt" -``` - -## Hidden parameters - -Params that are set as `hidden` in the JSON Schema are not shown in the help message. -To show these parameters, set the `validation.showHiddenParams = true` configuration option - -## Coloured logs - -By default, the help output is coloured using ANSI escape codes. - -If you prefer, you can disable these by using the argument monochrome_logs, e.g. `paramsHelp(monochrome_logs: true)`. Alternatively this can be set at a global level via parameter `--monochrome_logs` or adding `params.monochrome_logs = true` to a configuration file. `--monochromeLogs` or `params.monochromeLogs` is also supported. - -=== "Default (coloured)" - - ![Default help output](../images/help_not_monochrome_logs.png) - -=== "Monochrome logs" - - ![Default help output](../images/help_monochrome_logs.png) + See [`nextflow-io/nextflow#3984`](https://github.com/nextflow-io/nextflow/issues/3984). \ No newline at end of file From d5997851ac9f0ef90186176acd3e157c561c8c1c Mon Sep 17 00:00:00 2001 From: Nicolas Vannieuwkerke Date: Wed, 14 Aug 2024 13:05:53 +0200 Subject: [PATCH 03/12] small fix to ungrouped params --- .../main/nextflow/validation/HelpMessage.groovy | 16 ++++++++-------- .../src/main/nextflow/validation/Utils.groovy | 6 +++--- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/plugins/nf-schema/src/main/nextflow/validation/HelpMessage.groovy b/plugins/nf-schema/src/main/nextflow/validation/HelpMessage.groovy index 995dc99..6932919 100644 --- a/plugins/nf-schema/src/main/nextflow/validation/HelpMessage.groovy +++ b/plugins/nf-schema/src/main/nextflow/validation/HelpMessage.groovy @@ -125,9 +125,9 @@ class HelpMessage { def Map visibleParamsMap = paramsMap.collectEntries { key, Map value -> [key, removeHidden(value)]} def Map parsedParams = showNested ? visibleParamsMap.collectEntries { key, Map value -> [key, flattenNestedSchemaMap(value)] } : visibleParamsMap def Integer maxChars = Utils.paramsMaxChars(parsedParams) + 1 - if (parsedParams.containsKey(null)) { - def Map ungroupedParams = parsedParams[null] - parsedParams.remove(null) + if (parsedParams.containsKey("Other parameters")) { + def Map ungroupedParams = parsedParams["Other parameters"] + parsedParams.remove("Other parameters") helpMessage += getHelpListParams(ungroupedParams, maxChars + 2).collect { it[2..it.length()-1] }.join("\n") + "\n\n" @@ -216,18 +216,18 @@ class HelpMessage { // This function adds the help parameters to the main parameters map as ungrouped parameters // private void addHelpParameters() { - if (!paramsMap.containsKey(null)) { - paramsMap[null] = [:] + if (!paramsMap.containsKey("Other parameters")) { + paramsMap["Other parameters"] = [:] } - paramsMap[null][config.help.shortParameter] = [ + paramsMap["Other parameters"][config.help.shortParameter] = [ "type": ["boolean", "string"], "description": "Show the help message for all top level parameters. When a parameter is given to `--${config.help.shortParameter}`, the full help message of that parameter will be printed." ] - paramsMap[null][config.help.fullParameter] = [ + paramsMap["Other parameters"][config.help.fullParameter] = [ "type": "boolean", "description": "Show the help message for all non-hidden parameters." ] - paramsMap[null][config.help.showHiddenParameter] = [ + paramsMap["Other parameters"][config.help.showHiddenParameter] = [ "type": "boolean", "description": "Show all hidden parameters in the help message. This needs to be used in combination with `--${config.help.shortParameter}` or `--${config.help.fullParameter}`." ] diff --git a/plugins/nf-schema/src/main/nextflow/validation/Utils.groovy b/plugins/nf-schema/src/main/nextflow/validation/Utils.groovy index 736082d..1ff9a98 100644 --- a/plugins/nf-schema/src/main/nextflow/validation/Utils.groovy +++ b/plugins/nf-schema/src/main/nextflow/validation/Utils.groovy @@ -325,9 +325,9 @@ public class Utils { def paramsMap = [:] // Grouped params if (schema_defs) { - for (group in schema_defs) { - def Map group_property = (Map) group.value['properties'] // Gets the property object of the group - def String title = (String) group.value['title'] + schema_defs.each { String name, Map group -> + def Map group_property = (Map) group.get('properties') // Gets the property object of the group + def String title = (String) group.get('title') ?: name def sub_params = [:] group_property.each { innerkey, value -> sub_params.put(innerkey, value) From fc1d463ddc33e3237084ef85b5f0adb87c774e9b Mon Sep 17 00:00:00 2001 From: Nicolas Vannieuwkerke Date: Wed, 14 Aug 2024 13:27:08 +0200 Subject: [PATCH 04/12] update contribution docs --- docs/contributing/setup.md | 28 +++++++++++++++++-- .../nextflow_schema_specification.md | 25 ++++++++++++----- 2 files changed, 44 insertions(+), 9 deletions(-) diff --git a/docs/contributing/setup.md b/docs/contributing/setup.md index 0f28333..5282b52 100644 --- a/docs/contributing/setup.md +++ b/docs/contributing/setup.md @@ -13,9 +13,33 @@ 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 + + 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 diff --git a/docs/nextflow_schema/nextflow_schema_specification.md b/docs/nextflow_schema/nextflow_schema_specification.md index 11a9486..7cfcf9a 100644 --- a/docs/nextflow_schema/nextflow_schema_specification.md +++ b/docs/nextflow_schema/nextflow_schema_specification.md @@ -82,9 +82,7 @@ However, they will be displayed as ungrouped in tools working off the schema. ## Nested parameters -!!! warning "Warning (TLDR;)" - - Although the JSON Schema allows schema objects (eg.` params.foo.bar = "baz"`) or arrays, this is not supported by this plugin. +!!! example "New feature in v2.1.0" Nextflow config allows parameters to be nested as objects, for example: @@ -102,12 +100,25 @@ or on the CLI: nextflow run --foo.bar "baz" ``` -But - the current implementations of the Nextflow _schema_ do not (for now). +Nested parameters can be specified in the schema by adding a `properties` keyword to the root parameters: -This was done as a conscious decision when the code was first written, to try to reduce complexity. +```json +{ + "type": "object", + "properties": { + "nested": { // Annotation for the --nested parameter + "type": "object", // Parameters that contain subparameters need to have the "object" type + "properties": { // Add other parameters in here + "deep": { // Annotation for the --nested.deep parameter + "type": "string" + } + } + }, + } +} +``` -It would be great to implement this at some point - there is a GitHub issue to track the feature request here: -[`nf-core/tools#1554`](https://github.com/nf-core/tools/issues/1554). Contributions welcome! +There is no limit to how deeply nested parameters can be. Mind however that deeply nested parameters are not that user friendly and will create some very ugly help messages. It's adviced to not go deeper than two levels of nesting, but it's entirely possible to go deeper. ## Required parameters From 4a47c19fa2f10476cc7e603f3b65f513dbdbd329 Mon Sep 17 00:00:00 2001 From: Nicolas Vannieuwkerke Date: Wed, 14 Aug 2024 13:31:08 +0200 Subject: [PATCH 05/12] prettier --- docs/configuration/configuration.md | 4 ++-- docs/contributing/setup.md | 2 +- docs/migration_guide.md | 2 +- .../nextflow_schema_specification.md | 11 +++++++---- docs/parameters/help_text.md | 18 +++++++++--------- 5 files changed, 20 insertions(+), 17 deletions(-) diff --git a/docs/configuration/configuration.md b/docs/configuration/configuration.md index cca8512..b06e79c 100644 --- a/docs/configuration/configuration.md +++ b/docs/configuration/configuration.md @@ -56,7 +56,7 @@ validation.failUnrecognisedParams = // default: false ## showHiddenParams -!!! deprecated +!!! deprecated This configuration option has been deprecated since v2.1.0. Please use `validation.help.showHidden` instead. @@ -88,7 +88,7 @@ validation.defaultIgnoreParams = ["param1", "param2"] // default: [] ## help -The `validation.help` config scope can be used to configure the creation of the help message. +The `validation.help` config scope can be used to configure the creation of the help message. This scope contains the following options: diff --git a/docs/contributing/setup.md b/docs/contributing/setup.md index 5282b52..9656e66 100644 --- a/docs/contributing/setup.md +++ b/docs/contributing/setup.md @@ -18,7 +18,7 @@ To compile and run the tests use the following command: !!! warning 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 + 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 diff --git a/docs/migration_guide.md b/docs/migration_guide.md index 001bee2..a427431 100644 --- a/docs/migration_guide.md +++ b/docs/migration_guide.md @@ -289,4 +289,4 @@ The creation of the help message now needs to be enabled in the configuration fi command: "nextflow run my_pipeline --input input_file.csv" } } - ``` \ No newline at end of file + ``` diff --git a/docs/nextflow_schema/nextflow_schema_specification.md b/docs/nextflow_schema/nextflow_schema_specification.md index 7cfcf9a..4bfabee 100644 --- a/docs/nextflow_schema/nextflow_schema_specification.md +++ b/docs/nextflow_schema/nextflow_schema_specification.md @@ -106,14 +106,17 @@ Nested parameters can be specified in the schema by adding a `properties` keywor { "type": "object", "properties": { - "nested": { // Annotation for the --nested parameter + "nested": { + // Annotation for the --nested parameter "type": "object", // Parameters that contain subparameters need to have the "object" type - "properties": { // Add other parameters in here - "deep": { // Annotation for the --nested.deep parameter + "properties": { + // Add other parameters in here + "deep": { + // Annotation for the --nested.deep parameter "type": "string" } } - }, + } } } ``` diff --git a/docs/parameters/help_text.md b/docs/parameters/help_text.md index 08f3ceb..b23f017 100644 --- a/docs/parameters/help_text.md +++ b/docs/parameters/help_text.md @@ -91,12 +91,12 @@ There are three different help messages: ```bash --reference [object] A group of parameters to configure the reference sets --type [string] The analysis type (accepted: WES, WGS) - --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`. + --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 parameters - --input [string] The input samplesheet + --input [string] The input samplesheet --outdir [string] The output directory [default: results] ``` @@ -108,12 +108,12 @@ There are three different help messages: --reference.aligners.bwa [string] The BWA index --reference.aligners.bowtie [string] The BOWTIE index --type [string] The analysis type (accepted: WES, WGS) - --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`. + --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 parameters - --input [string] The input samplesheet + --input [string] The input samplesheet --outdir [string] The output directory [default: results] ``` @@ -212,4 +212,4 @@ Output: !!! warning We shouldn't be using `exit` as it kills the Nextflow head job in a way that is difficult to handle by systems that may be running it externally, but at the time of writing there is no good alternative. - See [`nextflow-io/nextflow#3984`](https://github.com/nextflow-io/nextflow/issues/3984). \ No newline at end of file + See [`nextflow-io/nextflow#3984`](https://github.com/nextflow-io/nextflow/issues/3984). From b29dea310590cf08ddc03c2a806b2d1d6a8972b7 Mon Sep 17 00:00:00 2001 From: Nicolas Vannieuwkerke Date: Wed, 14 Aug 2024 14:02:59 +0200 Subject: [PATCH 06/12] clarify the nested parameter name --- docs/nextflow_schema/nextflow_schema_specification.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/nextflow_schema/nextflow_schema_specification.md b/docs/nextflow_schema/nextflow_schema_specification.md index 4bfabee..0232f7a 100644 --- a/docs/nextflow_schema/nextflow_schema_specification.md +++ b/docs/nextflow_schema/nextflow_schema_specification.md @@ -106,13 +106,13 @@ Nested parameters can be specified in the schema by adding a `properties` keywor { "type": "object", "properties": { - "nested": { - // Annotation for the --nested parameter + "thisIsNested": { + // Annotation for the --thisIsNested parameter "type": "object", // Parameters that contain subparameters need to have the "object" type "properties": { // Add other parameters in here "deep": { - // Annotation for the --nested.deep parameter + // Annotation for the --thisIsNested.deep parameter "type": "string" } } From 67b385b3989c92440bce3b64df717e577252f473 Mon Sep 17 00:00:00 2001 From: Nicolas Vannieuwkerke <101190534+nvnieuwk@users.noreply.github.com> Date: Tue, 20 Aug 2024 11:29:25 +0200 Subject: [PATCH 07/12] Update docs/configuration/configuration.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Júlia Mir Pedrol --- docs/configuration/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/configuration.md b/docs/configuration/configuration.md index b06e79c..c9c766c 100644 --- a/docs/configuration/configuration.md +++ b/docs/configuration/configuration.md @@ -108,7 +108,7 @@ This option can be used to change the `--help` parameter to another parameter. T 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 expanded help message. +`--giveMeHelp` will now display the help message instead of `--help` for this example. This parameter will print out the help message. ### fullParameter From ac96cb85ae01deaea2546b8b80740f2ff090ba64 Mon Sep 17 00:00:00 2001 From: Nicolas Vannieuwkerke <101190534+nvnieuwk@users.noreply.github.com> Date: Tue, 20 Aug 2024 11:29:37 +0200 Subject: [PATCH 08/12] Update docs/configuration/configuration.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Júlia Mir Pedrol --- docs/configuration/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/configuration.md b/docs/configuration/configuration.md index c9c766c..63a55c4 100644 --- a/docs/configuration/configuration.md +++ b/docs/configuration/configuration.md @@ -128,7 +128,7 @@ This option can be used to change the `--showHidden` parameter to another parame validation.help.showHiddenParameter = "showMeThoseHiddenParams" // default: "showHidden" ``` -`--showHidden` will now make sure hidden parameters will be shown instead of `--showHidden` for this example. +`--showMeThoseHiddenParams ` will now make sure hidden parameters will be shown instead of `--showHidden` for this example. ### showHidden From 1d7c380feb42c30c95657dc3619a1da6816e09a1 Mon Sep 17 00:00:00 2001 From: Nicolas Vannieuwkerke <101190534+nvnieuwk@users.noreply.github.com> Date: Tue, 20 Aug 2024 11:30:46 +0200 Subject: [PATCH 09/12] Update docs/configuration/configuration.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Júlia Mir Pedrol --- docs/configuration/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/configuration.md b/docs/configuration/configuration.md index 63a55c4..909a191 100644 --- a/docs/configuration/configuration.md +++ b/docs/configuration/configuration.md @@ -170,7 +170,7 @@ Typical pipeline command: !!! example "This option does not affect `paramsHelp()`" -Any string provided to this option will printed after the help message. +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: "" From 5c41e619d4883ebd74e3f5f9befda83a81398ecb Mon Sep 17 00:00:00 2001 From: Nicolas Vannieuwkerke <101190534+nvnieuwk@users.noreply.github.com> Date: Tue, 20 Aug 2024 11:32:32 +0200 Subject: [PATCH 10/12] Update docs/nextflow_schema/nextflow_schema_specification.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Júlia Mir Pedrol --- docs/nextflow_schema/nextflow_schema_specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/nextflow_schema/nextflow_schema_specification.md b/docs/nextflow_schema/nextflow_schema_specification.md index 0232f7a..05f52c6 100644 --- a/docs/nextflow_schema/nextflow_schema_specification.md +++ b/docs/nextflow_schema/nextflow_schema_specification.md @@ -121,7 +121,7 @@ Nested parameters can be specified in the schema by adding a `properties` keywor } ``` -There is no limit to how deeply nested parameters can be. Mind however that deeply nested parameters are not that user friendly and will create some very ugly help messages. It's adviced to not go deeper than two levels of nesting, but it's entirely possible to go deeper. +There is no limit to how deeply nested parameters can be. Mind however that deeply nested parameters are not that user friendly and will create some very ugly help messages. It's adviced to not go deeper than two levels of nesting. ## Required parameters From 257e87cda999ab48f0e35c9e367d54c8eae4ec94 Mon Sep 17 00:00:00 2001 From: Nicolas Vannieuwkerke <101190534+nvnieuwk@users.noreply.github.com> Date: Tue, 20 Aug 2024 11:32:52 +0200 Subject: [PATCH 11/12] Update docs/parameters/help_text.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Júlia Mir Pedrol --- docs/parameters/help_text.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/parameters/help_text.md b/docs/parameters/help_text.md index b23f017..893efff 100644 --- a/docs/parameters/help_text.md +++ b/docs/parameters/help_text.md @@ -22,7 +22,7 @@ There are three different help messages: 1. Using `--help` will only show the top level parameters (`--input`, `--outdir`, `--reference` and `--type` in the example). The type, description, possible options and defaults of these parameters will also be added to the message if they are present in the JSON schema. 2. Using `--helpFull` will print all parameters (no matter how deeply nested they are) (`--input`, `--outdir`, `--reference.fasta`, `--reference.fai`, `--reference.aligners.bwa`, `--reference.aligners.bowtie` and `--type` in the example) -3. `--help` can also be used with a parameter given to it. This will print out a detailed help message of the parameter. This will also show and subparameters present for the parameter. +3. `--help` can also be used with a parameter given to it. This will print out a detailed help message of the parameter. This will also show the subparameters present for the parameter. === "JSON schema" From c3662c74216ea980f6b3d4cc892d325801b0818b Mon Sep 17 00:00:00 2001 From: Nicolas Vannieuwkerke Date: Tue, 20 Aug 2024 11:44:49 +0200 Subject: [PATCH 12/12] apply review comments --- docs/configuration/configuration.md | 6 +++--- docs/contributing/setup.md | 12 ++++++------ .../nextflow_schema/nextflow_schema_specification.md | 2 +- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/configuration/configuration.md b/docs/configuration/configuration.md index 909a191..e052a9d 100644 --- a/docs/configuration/configuration.md +++ b/docs/configuration/configuration.md @@ -140,7 +140,7 @@ validation.help.showHidden = // default: false ### beforeText -!!! example "This option does not affect `paramsHelp()`" +!!! 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. @@ -150,7 +150,7 @@ validation.help.beforeText = "Running pipeline version 1.0" // default: "" ### command -!!! example "This option does not affect `paramsHelp()`" +!!! 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. @@ -168,7 +168,7 @@ Typical pipeline command: ### afterText -!!! example "This option does not affect `paramsHelp()`" +!!! 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. diff --git a/docs/contributing/setup.md b/docs/contributing/setup.md index 9656e66..5b5cd1c 100644 --- a/docs/contributing/setup.md +++ b/docs/contributing/setup.md @@ -25,13 +25,13 @@ To compile and run the tests use the following command: rm -rf ~/.nextflow/plugins/nf-schema* ``` -Install the current version of the plugin in your `.nextflow/plugins` folder +- 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 +- Update or add the nf-schema plugin with the installed version in your test pipeline ```groovy title="nextflow.config" plugins { @@ -41,26 +41,26 @@ plugins { ## Launch it with a local version of Nextflow -Clone the Nextflow repo into a sibling directory +- 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