nextflow-io / nf-schema

Functionality for working with pipeline and sample sheet schema files in Nextflow pipelines
https://nextflow-io.github.io/nf-schema/
Apache License 2.0
12 stars 21 forks source link

Improvement/help messages #41

Closed nvnieuwk closed 3 months ago

nvnieuwk commented 3 months ago

This PR completely revamps the help messages.

List of changes:

  1. Help messages now automatically show instead of using the paramsHelp function. The paramsHelp function is still present for backwards compatibility but will no longer be updated. A deprecation warning will also be printed now to prompt the users to migrate to the new system. (Is there a need to keep this function fully supported?)
  2. Help messages can be configured using the following config options:
    • validation.help.enabled: Will check if the help parameters are given and print out the correct help message
    • validation.help.shortParameter: Change the parameter to use for the compact help message (--help by default)
    • validation.help.fullParameter: Change the parameter to use for the full help message (--helpFull by default)
    • validation.help.showHiddenParameter: Change the parameter to show hidden parameters in the help message (--showHidden by default)
    • validation.help.beforeText: Provides a way to add some custom text before the help message
    • validation.help.afterText: Provides a way to add some custom text after the help message
    • validation.help.command: Will add an example command to the help message
    • validation.help.showHidden: Enabling this options will make sure that the help message will also contain hidden parameters by default. This option replaces validation.showHiddenParameters, which will keep working for now but will also show a deprecation message.
  3. These 3 options are possible to get as a help message:
    • Option 1: using --help => A help message with the non-nested parameters (Styling has not been applied on this example, comments (#) are also not in the real output)
      
      # Ungrouped parameters
      --testparams                   [object]  (This parameter has sub-parameters. Use '--help testparams' to see all sub-parameters) 

Grouped Parameters

Input/output options --input [string] Path to comma-separated file containing information about the samples in the experiment. --nested_params [object] This is a nested parameter (This parameter has sub-parameters. Use '--help nested_params' to see all sub-parameters)


    - Option 2: using `--help <parameter>` => A detailed help message for the specified parameter. This also works for nested parameters

--nested_params description: This is a nested parameter options : --nested_params.deep.hello [string] hi --nested_params.deep.bool [boolean] boolean value --nested_params.bye [string] This is goodbye


    - Option 3: using `--helpFull` shows the help message from `--help` but with all nested parameters expanded

--testparams.test [integer]

Input/output options --input [string] Path to comma-separated file containing information about the samples in the experiment. --nested_params.deep.hello [string] hi --nested_params.deep.bool [boolean] boolean value --nested_params.bye [string] This is goodbye


4. Some other small changes 

TODOS:
- [x] Implement a better way to handle hidden files
- [x] Implement `validation.help.beforeText` and `validation.help.afterText`
- [x] Re-add the command option
- [x] Re-add the note about hidden parameters at the end of the help message
nvnieuwk commented 3 months ago

Nice! Could we test it with the nf-core/testpipeline to make sure that the current functionality can be replicated?

I used a version of the test pipeline to test out these features but I'll try it out on a new branch of the repo too :)

nvnieuwk commented 3 months ago

I'll go ahead and merge this into the other PR now :) Thanks for the reviews!