Added AsciiDoc k3kcli automation (#597)

* adding scripts for asciidoc cli generation

* fix small typos to align to existing docs

* added pandoc

* pandoc check

Author: enrichman

.github/workflows/test-e2e.yaml

@@ -20,8 +20,12 @@ jobs:
       with:
         go-version-file: go.mod
 
+    - name: Install Pandoc
+      run: sudo apt-get install pandoc
+
     - name: Validate
       run: make validate
+
   tests-e2e:
     runs-on: ubuntu-latest
     needs: validate

.github/workflows/test.yaml

@@ -37,6 +37,9 @@ jobs:
       with:
         go-version-file: go.mod
 
+    - name: Install Pandoc
+      run: sudo apt-get install pandoc
+
     - name: Validate
       run: make validate
 

Makefile

@@ -15,6 +15,7 @@ CRD_REF_DOCS_VER ?= v0.1.0
 GOLANGCI_LINT ?= go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@$(GOLANGCI_LINT_VERSION)
 GINKGO ?= go run github.com/onsi/ginkgo/v2/ginkgo@$(GINKGO_VERSION)
 CRD_REF_DOCS := go run github.com/elastic/crd-ref-docs@$(CRD_REF_DOCS_VER)
+PANDOC := $(shell which pandoc 2> /dev/null)
 
 ENVTEST ?= go run sigs.k8s.io/controller-runtime/tools/setup-envtest@$(ENVTEST_VERSION)
 ENVTEST_DIR ?= $(shell pwd)/.envtest
@@ -83,12 +84,21 @@ generate:	## Generate the CRDs specs
 	go generate ./...
 
 .PHONY: docs
-docs:	## Build the CRDs and CLI docs
+docs: docs-crds docs-cli	## Build the CRDs and CLI docs
+
+.PHONY: docs-crds
+docs-crds:	## Build the CRDs docs
 	$(CRD_REF_DOCS) --config=./docs/crds/config.yaml \
 		--renderer=markdown \
 		--source-path=./pkg/apis/k3k.io/v1beta1 \
 		--output-path=./docs/crds/crd-docs.md
-	@go run ./docs/cli/genclidoc.go
+
+.PHONY: docs-cli
+docs-cli:	## Build the CLI docs
+ifeq (, $(PANDOC))
+	$(error "pandoc not found in PATH.")
+endif
+	@./scripts/generate-cli-docs
 
 .PHONY: lint
 lint:	## Find any linting issues in the project

cli/cmds/cluster.go

@@ -7,7 +7,7 @@ import (
 func NewClusterCmd(appCtx *AppContext) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "cluster",
-		Short: "cluster command",
+		Short: "K3k cluster command.",
 	}
 
 	cmd.AddCommand(

cli/cmds/cluster_create.go

@@ -58,7 +58,7 @@ func NewClusterCreateCmd(appCtx *AppContext) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:     "create",
-		Short:   "Create new cluster",
+		Short:   "Create a new cluster.",
 		Example: "k3kcli cluster create [command options] NAME",
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			return validateCreateConfig(createConfig)

cli/cmds/cluster_delete.go

@@ -24,7 +24,7 @@ var keepData bool
 func NewClusterDeleteCmd(appCtx *AppContext) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "delete",
-		Short:   "Delete an existing cluster",
+		Short:   "Delete an existing cluster.",
 		Example: "k3kcli cluster delete [command options] NAME",
 		RunE:    delete(appCtx),
 		Args:    cobra.ExactArgs(1),

cli/cmds/cluster_list.go

@@ -16,7 +16,7 @@ import (
 func NewClusterListCmd(appCtx *AppContext) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "list",
-		Short:   "List all the existing cluster",
+		Short:   "List all existing clusters.",
 		Example: "k3kcli cluster list [command options]",
 		RunE:    list(appCtx),
 		Args:    cobra.NoArgs,

cli/cmds/kubeconfig.go

@@ -37,7 +37,7 @@ type GenerateKubeconfigConfig struct {
 func NewKubeconfigCmd(appCtx *AppContext) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "kubeconfig",
-		Short: "Manage kubeconfig for clusters",
+		Short: "Manage kubeconfig for clusters.",
 	}
 
 	cmd.AddCommand(
@@ -52,7 +52,7 @@ func NewKubeconfigGenerateCmd(appCtx *AppContext) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "generate",
-		Short: "Generate kubeconfig for clusters",
+		Short: "Generate kubeconfig for clusters.",
 		RunE:  generate(appCtx, cfg),
 		Args:  cobra.NoArgs,
 	}

cli/cmds/policy.go

@@ -7,7 +7,7 @@ import (
 func NewPolicyCmd(appCtx *AppContext) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "policy",
-		Short: "policy command",
+		Short: "K3k policy command.",
 	}
 
 	cmd.AddCommand(

cli/cmds/policy_create.go

@@ -30,7 +30,7 @@ func NewPolicyCreateCmd(appCtx *AppContext) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:     "create",
-		Short:   "Create new policy",
+		Short:   "Create a new policy.",
 		Example: "k3kcli policy create [command options] NAME",
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			switch config.mode {