Use an "umbrella task" for generated documentation

There may be project-specific documentation generation. The most prominent is the command line reference generation for
projects using Cobra. Another is Arduino CLI's gRPC interface documentation.

These project-specific generations should have dedicated tasks with appropriate names. A single umbrella task is used to
run all the documentation generation tasks the project has. This umbrella task uses a standardized name: `docs:generate`.
In this manner, the templates can be configured to be general purpose and work for all projects without requiring
significant changes to account for the specifics of their documentation generation requirements. In the event the project
does not generate any documentation content, the task can simply be left empty.

Author: per1234

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

@@ -2,6 +2,11 @@
 version: "3"
 
 tasks:
+  docs:generate:
+    desc: Create all generated documentation content
+    # This is an "umbrella" task used to call any documentation generation processes the project has.
+    # It can be left empty if there are none.
+
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
   markdown:lint:
     desc: Check for problems in Markdown files
@@ -17,6 +22,8 @@ tasks:
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
   markdown:check-links:
     desc: Check for broken links
+    deps:
+      - task: docs:generate
     cmds:
       - |
         if [[ "{{.OS}}" == "Windows_NT" ]]; then

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

@@ -2,10 +2,16 @@
 version: "3"
 
 tasks:
+  docs:generate:
+    desc: Create all generated documentation content
+    # This is an "umbrella" task used to call any documentation generation processes the project has.
+    # It can be left empty if there are none.
+
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-mkdocs-task/Taskfile.yml
   website:check:
     desc: Check whether the MkDocs-based website will build
     deps:
+      - task: docs:generate
       - task: poetry:install-deps
     cmds:
       - poetry run mkdocs build --strict
@@ -14,6 +20,7 @@ tasks:
   website:serve:
     desc: Run website locally
     deps:
+      - task: docs:generate
       - task: poetry:install-deps
     cmds:
       - poetry run mkdocs serve

workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/Taskfile.yml

@@ -5,12 +5,19 @@ vars:
 
 tasks:
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/Taskfile.yml
-  docs:gen:
-    desc: Generate command reference
+  docs:generate:
+    desc: Create all generated documentation content
+    deps:
+      - task: go:cli-docs
+      # Make the formatting consistent with the non-generated Markdown
+      - task: general:format-prettier
+
+  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/Taskfile.yml
+  go:cli-docs:
+    desc: Generate command line interface reference documentation
     dir: ./docsgen
     cmds:
       # Command examples use os.Args[0] so the docs generation binary must have the same filename as the project
       - go build -o {{.PROJECT_NAME}}{{exeExt}}
       # The binary is invoked like this instead of `./{{.PROJECT_NAME}}` to remove the `./` chars from the examples
       - PATH=. {{.PROJECT_NAME}} ../docs/commands
-      - task: docs:format

workflow-templates/check-markdown-task.md

@@ -28,6 +28,10 @@ The code style defined in `.markdownlint.yml` is the official standardized style
 
 ### Configuration
 
+#### Taskfile
+
+Add any documentation generation processes to the `docs:generate` umbrella task.
+
 #### markdownlint
 
 In the event the repository contains externally maintained Markdown files, `markdownlint` can be configured to ignore them via a `.markdownlintignore` file:

workflow-templates/check-mkdocs-task.md

@@ -24,6 +24,12 @@ See [the "Deploy Website" (MkDocs, Poetry) workflow documentation](deploy-mkdocs
 
 ### Configuration
 
+#### Taskfile
+
+Add any documentation generation processes to the `docs:generate` umbrella task.
+
+#### MkDocs
+
 See [the "Deploy Website" (MkDocs, Poetry) workflow documentation](deploy-mkdocs-poetry.md#configuration)
 
 ### Readme badge