From c45bb9ea59c0c6328d5654a58b207919e873d0c6 Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 15 Aug 2021 17:41:04 -0700 Subject: [PATCH 1/3] Use more common Cobra command root function in "docsgen" template The function that creates the Cobra CLI command root is declared by each project, and so might have any name. As it was the most advanced in general, I used Arduino Lint as the source for the Cobra-based project website template assets. However, I noticed that Arduino CLI and Arduino Firmware Uploader both use the function name `cli.NewCommand()`, so I think this is more likely to be the name used by tooling projects this template is applied to. --- workflow-templates/assets/cobra/docsgen/main.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/workflow-templates/assets/cobra/docsgen/main.go b/workflow-templates/assets/cobra/docsgen/main.go index f50be3f0..c65e4110 100644 --- a/workflow-templates/assets/cobra/docsgen/main.go +++ b/workflow-templates/assets/cobra/docsgen/main.go @@ -31,7 +31,7 @@ func main() { os.MkdirAll(os.Args[1], 0755) // Create the output folder if it doesn't already exist - cli := cli.Root() + cli := cli.NewCommand() cli.DisableAutoGenTag = true // Disable addition of auto-generated date stamp err := doc.GenMarkdownTree(cli, os.Args[1]) if err != nil { From 8024b90698ea6a73703851adc68daa3d4340c870 Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 15 Aug 2021 17:50:52 -0700 Subject: [PATCH 2/3] Document project-specific command root generation function The function that creates the Cobra CLI command root is declared by each project, and so might have any name. The "docsgen" program that generates the command line reference content for the website calls this function, so it will be necessary for the appropriate function to be added to the program when it is added to a project. Previously, there was no documentation of this project-specific component of the "template", which could result in confusion when it was applied to a project that happens to have a different function name from the `cli.NewCommand()` used by the "template" docsgen code. --- workflow-templates/assets/cobra/docsgen/main.go | 1 + workflow-templates/deploy-cobra-mkdocs-versioned-poetry.md | 4 +++- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/workflow-templates/assets/cobra/docsgen/main.go b/workflow-templates/assets/cobra/docsgen/main.go index c65e4110..4038d1fa 100644 --- a/workflow-templates/assets/cobra/docsgen/main.go +++ b/workflow-templates/assets/cobra/docsgen/main.go @@ -31,6 +31,7 @@ func main() { os.MkdirAll(os.Args[1], 0755) // Create the output folder if it doesn't already exist + // TODO: Replace `cli.NewCommand()` with the project's Cobra CLI package function for command root cli := cli.NewCommand() cli.DisableAutoGenTag = true // Disable addition of auto-generated date stamp err := doc.GenMarkdownTree(cli, os.Args[1]) diff --git a/workflow-templates/deploy-cobra-mkdocs-versioned-poetry.md b/workflow-templates/deploy-cobra-mkdocs-versioned-poetry.md index b59b2ba8..33b90589 100644 --- a/workflow-templates/deploy-cobra-mkdocs-versioned-poetry.md +++ b/workflow-templates/deploy-cobra-mkdocs-versioned-poetry.md @@ -45,7 +45,9 @@ If there are any additional documentation generation tasks, add them to the `doc #### `docsgen` - [`go.mod`](assets/cobra/docsgen/go.mod) - replace `MODULE_NAME` with the project's module name. -- [`main.go`](assets/cobra/docsgen/main.go) - replace `CLI_PACKAGE_NAME` with the project's Cobra CLI package name +- [`main.go`](assets/cobra/docsgen/main.go) + - replace `CLI_PACKAGE_NAME` with the project's Cobra CLI package name + - replace `cli.NewCommand()` with the project's Cobra CLI package function for [command root](https://github.com/spf13/cobra/blob/master/user_guide.md#create-rootcmd) generation Run the following command from the `docsgen/` folder: From 89886b3b5f6379036a15d5c88d7868d3290dfcf0 Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 15 Aug 2021 17:57:48 -0700 Subject: [PATCH 3/3] Use explicit package name in "docsgen" CLI package import The template "docsgen" program for generating the website Cobra CLI reference content relies on the project's Cobra CLI package being named `cli`. But this is not guaranteed to be so, and in fact the Cobra documentation uses `cmd` instead. Confusion caused by applying the program to projects that use different package names will be avoided by specifying an explicit package name in the import statement. --- workflow-templates/assets/cobra/docsgen/main.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/workflow-templates/assets/cobra/docsgen/main.go b/workflow-templates/assets/cobra/docsgen/main.go index 4038d1fa..08072899 100644 --- a/workflow-templates/assets/cobra/docsgen/main.go +++ b/workflow-templates/assets/cobra/docsgen/main.go @@ -18,8 +18,8 @@ package main import ( "os" - // TODO: Replace CLI_PACKAGE_NAME with the project's Cobra CLI package name - "CLI_PACKAGE_NAME" + // TODO: Replace CLI_PACKAGE_NAME with the project's Cobra CLI package import path + cli "CLI_PACKAGE_NAME" "github.com/spf13/cobra/doc" )