Merge pull request #615 from per1234/document-task-params

Document task environment variable parameters

Author: per1234

Taskfile.yml

@@ -730,11 +730,12 @@ tasks:
             -s "{{.SCHEMA_PATH}}" \
             -d "{{.DATA_PATH}}"
 
-  # Parameter variables:
-  # - PROJECT_PATH: path of the npm-managed project. Default value: "./"
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/npm-task/Taskfile.yml
   npm:install-deps:
-    desc: Install dependencies managed by npm
+    desc: |
+      Install dependencies managed by npm.
+      Environment variable parameters:
+      - PROJECT_PATH: Path of the npm-managed project (default: "./").
     run: when_changed
     dir: |
       "{{default "./" .PROJECT_PATH}}"
@@ -756,11 +757,12 @@ tasks:
             --location project \
             fix
 
-  # Parameter variables:
-  # - PROJECT_PATH: path of the npm-managed project. Default value: "./"
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-npm-task/Taskfile.yml
   npm:validate:
-    desc: Validate npm configuration files against their JSON schema
+    desc: |
+      Validate npm configuration files against their JSON schema.
+      Environment variable parameters:
+      - PROJECT_PATH: Path of the npm-managed project (default: "./").
     deps:
       - task: npm:install-deps
     vars:
@@ -956,11 +958,12 @@ tasks:
     cmds:
       - poetry run pytest workflow-templates/assets/deploy-mkdocs-versioned/siteversion/tests
 
-  # Parameter variables:
-  # - SCRIPT_PATH: path of the script to be checked.
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml
   shell:check:
-    desc: Check for problems with shell scripts
+    desc: |
+      Check for problems with shell scripts.
+      Environment variable parameters:
+      - SCRIPT_PATH: path of the script to be checked.
     cmds:
       - |
         if [[ "{{.SCRIPT_PATH}}" == "" ]]; then
@@ -979,11 +982,12 @@ tasks:
           --format={{default "tty" .SHELLCHECK_FORMAT}} \
           "{{.SCRIPT_PATH}}"
 
-  # Parameter variables:
-  # - SCRIPT_PATH: path of the script to be checked.
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml
   shell:check-mode:
-    desc: Check for non-executable shell scripts
+    desc: |
+      Check for non-executable shell scripts.
+      Environment variable parameters:
+      - SCRIPT_PATH: path of the script to be checked.
     cmds:
       - |
         if [[ "{{.SCRIPT_PATH}}" == "" ]]; then
@@ -994,11 +998,12 @@ tasks:
       - |
         test -x "{{.SCRIPT_PATH}}"
 
-  # Parameter variables:
-  # - SCRIPT_PATH: path of the script to be formatted.
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml
   shell:format:
-    desc: Format shell script files
+    desc: |
+      Format shell script files.
+      Environment variable parameters:
+      - SCRIPT_PATH: path of the script to be formatted.
     cmds:
       - |
         if [[ "{{.SCRIPT_PATH}}" == "" ]]; then
@@ -1013,7 +1018,9 @@ tasks:
         fi
       - shfmt -w "{{.SCRIPT_PATH}}"
 
-  # Make a temporary file named according to the passed TEMPLATE variable and print the path passed to stdout
+  # Make a temporary file and print the path passed to stdout.
+  # Environment variable parameters:
+  # - TEMPLATE: template for the format of the filename.
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/windows-task/Taskfile.yml
   utility:mktemp-file:
     vars:
@@ -1034,7 +1041,9 @@ tasks:
         vars:
           RAW_PATH: "{{.RAW_PATH}}"
 
-  # Print a normalized version of the path passed via the RAW_PATH variable to stdout
+  # Print a normalized version of the path to stdout.
+  # Environment variable parameters:
+  # - RAW_PATH: the path to be normalized.
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/windows-task/Taskfile.yml
   utility:normalize-path:
     cmds:
@@ -1047,6 +1056,8 @@ tasks:
           echo "{{.RAW_PATH}}"
         fi
 
+  # Environment variable parameters:
+  # - YAMLLINT_FORMAT: yamllint output format (default: colored).
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-yaml-task/Taskfile.yml
   yaml:lint:
     desc: Check for problems with YAML files

workflow-templates/assets/check-go-task/Taskfile.yml

@@ -4,21 +4,32 @@ version: "3"
 tasks:
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml
   go:fix:
-    desc: Modernize usages of outdated APIs
+    desc: |
+      Modernize usages of outdated APIs.
+      Environment variable parameters:
+      - GO_MODULE_PATH: Path of the Go module root (default: {{.DEFAULT_GO_MODULE_PATH}}).
+      - GO_PACKAGES: List of Go packages to modernize (default: all packages of the module).
     dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}"
     cmds:
       - go fix {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}}
 
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml
   go:format:
-    desc: Format Go code
+    desc: |
+      Format Go code.
+      Environment variable parameters:
+      - GO_MODULE_PATH: Path of the Go module root (default: {{.DEFAULT_GO_MODULE_PATH}}).
+      - GO_PACKAGES: List of Go packages to modernize (default: all packages of the module).
     dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}"
     cmds:
       - go fmt {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}}
 
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml
   go:lint:
-    desc: Lint Go code
+    desc: |
+      Lint Go code
+      Environment variable parameters:
+      - GO_MODULE_PATH: Path of the Go module root (default: {{.DEFAULT_GO_MODULE_PATH}}).
     dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}"
     cmds:
       - |

workflow-templates/assets/check-npm-task/Taskfile.yml

@@ -17,11 +17,12 @@ tasks:
             --location project \
             fix
 
-  # Parameter variables:
-  # - PROJECT_PATH: path of the npm-managed project. Default value: "./"
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-npm-task/Taskfile.yml
   npm:validate:
-    desc: Validate npm configuration files against their JSON schema
+    desc: |
+      Validate npm configuration files against their JSON schema.
+      Environment variable parameters:
+      - PROJECT_PATH: Path of the npm-managed project (default: "./").
     deps:
       - task: npm:install-deps
     vars:

workflow-templates/assets/check-shell-task/Taskfile.yml

@@ -2,11 +2,12 @@
 version: "3"
 
 tasks:
-  # Parameter variables:
-  # - SCRIPT_PATH: path of the script to be checked.
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml
   shell:check:
-    desc: Check for problems with shell scripts
+    desc: |
+      Check for problems with shell scripts.
+      Environment variable parameters:
+      - SCRIPT_PATH: path of the script to be checked.
     cmds:
       - |
         if [[ "{{.SCRIPT_PATH}}" == "" ]]; then
@@ -25,11 +26,12 @@ tasks:
           --format={{default "tty" .SHELLCHECK_FORMAT}} \
           "{{.SCRIPT_PATH}}"
 
-  # Parameter variables:
-  # - SCRIPT_PATH: path of the script to be checked.
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml
   shell:check-mode:
-    desc: Check for non-executable shell scripts
+    desc: |
+      Check for non-executable shell scripts.
+      Environment variable parameters:
+      - SCRIPT_PATH: path of the script to be checked.
     cmds:
       - |
         if [[ "{{.SCRIPT_PATH}}" == "" ]]; then
@@ -40,11 +42,12 @@ tasks:
       - |
         test -x "{{.SCRIPT_PATH}}"
 
-  # Parameter variables:
-  # - SCRIPT_PATH: path of the script to be formatted.
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml
   shell:format:
-    desc: Format shell script files
+    desc: |
+      Format shell script files.
+      Environment variable parameters:
+      - SCRIPT_PATH: path of the script to be formatted.
     cmds:
       - |
         if [[ "{{.SCRIPT_PATH}}" == "" ]]; then

workflow-templates/assets/check-toc-task/Taskfile.yml

@@ -4,7 +4,11 @@ version: "3"
 tasks:
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-toc-task/Taskfile.yml
   markdown:toc:
-    desc: Update the table of contents
+    desc: |
+      Update the table of contents.
+      Environment variable parameters:
+      - MAX_DEPTH: maximum heading depth for inclusion in ToC.
+      - FILE_PATH: path to the file that contains the ToC.
     deps:
       - task: npm:install-deps
     cmds:

workflow-templates/assets/check-yaml-task/Taskfile.yml

@@ -2,6 +2,8 @@
 version: "3"
 
 tasks:
+  # Environment variable parameters:
+  # - YAMLLINT_FORMAT: yamllint output format (default: colored).
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-yaml-task/Taskfile.yml
   yaml:lint:
     desc: Check for problems with YAML files

workflow-templates/assets/npm-task/Taskfile.yml

@@ -2,11 +2,12 @@
 version: "3"
 
 tasks:
-  # Parameter variables:
-  # - PROJECT_PATH: path of the npm-managed project. Default value: "./"
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/npm-task/Taskfile.yml
   npm:install-deps:
-    desc: Install dependencies managed by npm
+    desc: |
+      Install dependencies managed by npm.
+      Environment variable parameters:
+      - PROJECT_PATH: Path of the npm-managed project (default: "./").
     run: when_changed
     dir: |
       "{{default "./" .PROJECT_PATH}}"

workflow-templates/assets/windows-task/Taskfile.yml

@@ -2,7 +2,9 @@
 version: "3"
 
 tasks:
-  # Make a temporary file named according to the passed TEMPLATE variable and print the path passed to stdout
+  # Make a temporary file and print the path passed to stdout.
+  # Environment variable parameters:
+  # - TEMPLATE: template for the format of the filename.
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/windows-task/Taskfile.yml
   utility:mktemp-file:
     vars:
@@ -13,7 +15,9 @@ tasks:
         vars:
           RAW_PATH: "{{.RAW_PATH}}"
 
-  # Print a normalized version of the path passed via the RAW_PATH variable to stdout
+  # Print a normalized version of the path to stdout.
+  # Environment variable parameters:
+  # - RAW_PATH: the path to be normalized.
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/windows-task/Taskfile.yml
   utility:normalize-path:
     cmds: