From c16eae99c7f6d324c5a7f2f842617ad731f7d232 Mon Sep 17 00:00:00 2001 From: Enrico Candino Date: Wed, 7 Jan 2026 11:16:40 +0100 Subject: [PATCH] Added AsciiDoc `k3kcli` automation (#597) * adding scripts for asciidoc cli generation * fix small typos to align to existing docs * added pandoc * pandoc check --- .github/workflows/test-e2e.yaml | 4 + .github/workflows/test.yaml | 3 + Makefile | 14 +- cli/cmds/cluster.go | 2 +- cli/cmds/cluster_create.go | 2 +- cli/cmds/cluster_delete.go | 2 +- cli/cmds/cluster_list.go | 2 +- cli/cmds/kubeconfig.go | 4 +- cli/cmds/policy.go | 2 +- cli/cmds/policy_create.go | 2 +- cli/cmds/policy_delete.go | 2 +- cli/cmds/policy_list.go | 2 +- cli/cmds/root.go | 2 +- docs/cli/convert.lua | 25 +++ docs/cli/k3kcli.adoc | 283 +++++++++++++++++++++++++ docs/cli/k3kcli.md | 8 +- docs/cli/k3kcli_cluster.md | 10 +- docs/cli/k3kcli_cluster_create.md | 4 +- docs/cli/k3kcli_cluster_delete.md | 4 +- docs/cli/k3kcli_cluster_list.md | 4 +- docs/cli/k3kcli_kubeconfig.md | 6 +- docs/cli/k3kcli_kubeconfig_generate.md | 4 +- docs/cli/k3kcli_policy.md | 10 +- docs/cli/k3kcli_policy_create.md | 4 +- docs/cli/k3kcli_policy_delete.md | 4 +- docs/cli/k3kcli_policy_list.md | 4 +- scripts/generate-cli-docs | 42 ++++ 27 files changed, 411 insertions(+), 44 deletions(-) create mode 100644 docs/cli/convert.lua create mode 100644 docs/cli/k3kcli.adoc create mode 100755 scripts/generate-cli-docs diff --git a/.github/workflows/test-e2e.yaml b/.github/workflows/test-e2e.yaml index f5f46e0b..5c776b50 100644 --- a/.github/workflows/test-e2e.yaml +++ b/.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 diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index 9d504975..eafcfeec 100644 --- a/.github/workflows/test.yaml +++ b/.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 diff --git a/Makefile b/Makefile index 1f4158a1..d4c192a2 100644 --- a/Makefile +++ b/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 diff --git a/cli/cmds/cluster.go b/cli/cmds/cluster.go index fc96bbb7..f7cd7113 100644 --- a/cli/cmds/cluster.go +++ b/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( diff --git a/cli/cmds/cluster_create.go b/cli/cmds/cluster_create.go index c4fcdbea..57a5c566 100644 --- a/cli/cmds/cluster_create.go +++ b/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) diff --git a/cli/cmds/cluster_delete.go b/cli/cmds/cluster_delete.go index dbd6dbca..115e70ec 100644 --- a/cli/cmds/cluster_delete.go +++ b/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), diff --git a/cli/cmds/cluster_list.go b/cli/cmds/cluster_list.go index b93d135c..7db01a70 100644 --- a/cli/cmds/cluster_list.go +++ b/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, diff --git a/cli/cmds/kubeconfig.go b/cli/cmds/kubeconfig.go index 4efe07ec..39763fd4 100644 --- a/cli/cmds/kubeconfig.go +++ b/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, } diff --git a/cli/cmds/policy.go b/cli/cmds/policy.go index 1853c82f..10a1064b 100644 --- a/cli/cmds/policy.go +++ b/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( diff --git a/cli/cmds/policy_create.go b/cli/cmds/policy_create.go index b6c2db1d..22c14ceb 100644 --- a/cli/cmds/policy_create.go +++ b/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 { diff --git a/cli/cmds/policy_delete.go b/cli/cmds/policy_delete.go index 5077f59b..2e3f8bbd 100644 --- a/cli/cmds/policy_delete.go +++ b/cli/cmds/policy_delete.go @@ -14,7 +14,7 @@ import ( func NewPolicyDeleteCmd(appCtx *AppContext) *cobra.Command { return &cobra.Command{ Use: "delete", - Short: "Delete an existing policy", + Short: "Delete an existing policy.", Example: "k3kcli policy delete [command options] NAME", RunE: policyDeleteAction(appCtx), Args: cobra.ExactArgs(1), diff --git a/cli/cmds/policy_list.go b/cli/cmds/policy_list.go index 70e304b7..2080f788 100644 --- a/cli/cmds/policy_list.go +++ b/cli/cmds/policy_list.go @@ -15,7 +15,7 @@ import ( func NewPolicyListCmd(appCtx *AppContext) *cobra.Command { return &cobra.Command{ Use: "list", - Short: "List all the existing policies", + Short: "List all existing policies.", Example: "k3kcli policy list [command options]", RunE: policyList(appCtx), Args: cobra.NoArgs, diff --git a/cli/cmds/root.go b/cli/cmds/root.go index 9caeb9cd..7de3f100 100644 --- a/cli/cmds/root.go +++ b/cli/cmds/root.go @@ -36,7 +36,7 @@ func NewRootCmd() *cobra.Command { rootCmd := &cobra.Command{ SilenceUsage: true, Use: "k3kcli", - Short: "CLI for K3K", + Short: "CLI for K3K.", Version: buildinfo.Version, PersistentPreRunE: func(cmd *cobra.Command, args []string) error { InitializeConfig(cmd) diff --git a/docs/cli/convert.lua b/docs/cli/convert.lua new file mode 100644 index 00000000..db796202 --- /dev/null +++ b/docs/cli/convert.lua @@ -0,0 +1,25 @@ +local deleting_see_also = false + +function Header(el) + -- If we hit "SEE ALSO", start deleting and remove the header itself + if pandoc.utils.stringify(el):upper() == "SEE ALSO" then + deleting_see_also = true + return {} + end + -- If we hit any other header, stop deleting + deleting_see_also = false + return el +end + +function BulletList(el) + if deleting_see_also then + return {} -- Deletes the list of links + end + return el +end + +function CodeBlock(el) + -- Forces the ---- separator + local content = "----\n" .. el.text .. "\n----\n\n" + return pandoc.RawBlock('asciidoc', content) +end diff --git a/docs/cli/k3kcli.adoc b/docs/cli/k3kcli.adoc new file mode 100644 index 00000000..edcff88f --- /dev/null +++ b/docs/cli/k3kcli.adoc @@ -0,0 +1,283 @@ +== k3kcli + +CLI for K3K. + +=== Options + +---- + --debug Turn on debug logs + -h, --help help for k3kcli + --kubeconfig string kubeconfig path ($HOME/.kube/config or $KUBECONFIG if set) +---- + +== k3kcli cluster + +K3k cluster command. + +=== Options + +---- + -h, --help help for cluster +---- + +=== Options inherited from parent commands + +---- + --debug Turn on debug logs + --kubeconfig string kubeconfig path ($HOME/.kube/config or $KUBECONFIG if set) +---- + +== k3kcli cluster create + +Create a new cluster. + +---- +k3kcli cluster create [flags] +---- + +=== Examples + +---- +k3kcli cluster create [command options] NAME +---- + +=== Options + +---- + --agent-args strings agents extra arguments + --agent-envs strings agents extra Envs + --agents int number of agents + --annotations stringArray Annotations to add to the cluster object (e.g. key=value) + --cluster-cidr string cluster CIDR + --custom-certs string The path for custom certificate directory + -h, --help help for create + --kubeconfig-server string override the kubeconfig server host + --labels stringArray Labels to add to the cluster object (e.g. key=value) + --mirror-host-nodes Mirror Host Cluster Nodes + --mode string k3k mode type (shared, virtual) (default "shared") + -n, --namespace string namespace of the k3k cluster + --persistence-type string persistence mode for the nodes (dynamic, ephemeral) (default "dynamic") + --policy string The policy to create the cluster in + --server-args strings servers extra arguments + --server-envs strings servers extra Envs + --servers int number of servers (default 1) + --service-cidr string service CIDR + --storage-class-name string storage class name for dynamic persistence type + --storage-request-size string storage size for dynamic persistence type + --timeout duration The timeout for waiting for the cluster to become ready (e.g., 10s, 5m, 1h). (default 3m0s) + --token string token of the cluster + --version string k3s version +---- + +=== Options inherited from parent commands + +---- + --debug Turn on debug logs + --kubeconfig string kubeconfig path ($HOME/.kube/config or $KUBECONFIG if set) +---- + +== k3kcli cluster delete + +Delete an existing cluster. + +---- +k3kcli cluster delete [flags] +---- + +=== Examples + +---- +k3kcli cluster delete [command options] NAME +---- + +=== Options + +---- + -h, --help help for delete + --keep-data keeps persistence volumes created for the cluster after deletion + -n, --namespace string namespace of the k3k cluster +---- + +=== Options inherited from parent commands + +---- + --debug Turn on debug logs + --kubeconfig string kubeconfig path ($HOME/.kube/config or $KUBECONFIG if set) +---- + +== k3kcli cluster list + +List all existing clusters. + +---- +k3kcli cluster list [flags] +---- + +=== Examples + +---- +k3kcli cluster list [command options] +---- + +=== Options + +---- + -h, --help help for list + -n, --namespace string namespace of the k3k cluster +---- + +=== Options inherited from parent commands + +---- + --debug Turn on debug logs + --kubeconfig string kubeconfig path ($HOME/.kube/config or $KUBECONFIG if set) +---- + +== k3kcli kubeconfig + +Manage kubeconfig for clusters. + +=== Options + +---- + -h, --help help for kubeconfig +---- + +=== Options inherited from parent commands + +---- + --debug Turn on debug logs + --kubeconfig string kubeconfig path ($HOME/.kube/config or $KUBECONFIG if set) +---- + +== k3kcli kubeconfig generate + +Generate kubeconfig for clusters. + +---- +k3kcli kubeconfig generate [flags] +---- + +=== Options + +---- + --altNames strings altNames of the generated certificates for the kubeconfig + --cn string Common name (CN) of the generated certificates for the kubeconfig (default "system:admin") + --config-name string the name of the generated kubeconfig file + --expiration-days int Expiration date of the certificates used for the kubeconfig (default 365) + -h, --help help for generate + --kubeconfig-server string override the kubeconfig server host + --name string cluster name + -n, --namespace string namespace of the k3k cluster + --org strings Organization name (ORG) of the generated certificates for the kubeconfig +---- + +=== Options inherited from parent commands + +---- + --debug Turn on debug logs + --kubeconfig string kubeconfig path ($HOME/.kube/config or $KUBECONFIG if set) +---- + +== k3kcli policy + +K3k policy command. + +=== Options + +---- + -h, --help help for policy +---- + +=== Options inherited from parent commands + +---- + --debug Turn on debug logs + --kubeconfig string kubeconfig path ($HOME/.kube/config or $KUBECONFIG if set) +---- + +== k3kcli policy create + +Create a new policy. + +---- +k3kcli policy create [flags] +---- + +=== Examples + +---- +k3kcli policy create [command options] NAME +---- + +=== Options + +---- + --annotations stringArray Annotations to add to the policy object (e.g. key=value) + -h, --help help for create + --labels stringArray Labels to add to the policy object (e.g. key=value) + --mode string The allowed mode type of the policy (default "shared") + --namespace strings The namespaces where to bind the policy + --overwrite Overwrite namespace binding of existing policy +---- + +=== Options inherited from parent commands + +---- + --debug Turn on debug logs + --kubeconfig string kubeconfig path ($HOME/.kube/config or $KUBECONFIG if set) +---- + +== k3kcli policy delete + +Delete an existing policy. + +---- +k3kcli policy delete [flags] +---- + +=== Examples + +---- +k3kcli policy delete [command options] NAME +---- + +=== Options + +---- + -h, --help help for delete +---- + +=== Options inherited from parent commands + +---- + --debug Turn on debug logs + --kubeconfig string kubeconfig path ($HOME/.kube/config or $KUBECONFIG if set) +---- + +== k3kcli policy list + +List all existing policies. + +---- +k3kcli policy list [flags] +---- + +=== Examples + +---- +k3kcli policy list [command options] +---- + +=== Options + +---- + -h, --help help for list +---- + +=== Options inherited from parent commands + +---- + --debug Turn on debug logs + --kubeconfig string kubeconfig path ($HOME/.kube/config or $KUBECONFIG if set) +---- diff --git a/docs/cli/k3kcli.md b/docs/cli/k3kcli.md index d261eb14..72d8453a 100644 --- a/docs/cli/k3kcli.md +++ b/docs/cli/k3kcli.md @@ -1,6 +1,6 @@ ## k3kcli -CLI for K3K +CLI for K3K. ### Options @@ -12,7 +12,7 @@ CLI for K3K ### SEE ALSO -* [k3kcli cluster](k3kcli_cluster.md) - cluster command -* [k3kcli kubeconfig](k3kcli_kubeconfig.md) - Manage kubeconfig for clusters -* [k3kcli policy](k3kcli_policy.md) - policy command +* [k3kcli cluster](k3kcli_cluster.md) - K3k cluster command. +* [k3kcli kubeconfig](k3kcli_kubeconfig.md) - Manage kubeconfig for clusters. +* [k3kcli policy](k3kcli_policy.md) - K3k policy command. diff --git a/docs/cli/k3kcli_cluster.md b/docs/cli/k3kcli_cluster.md index dd0e9cff..cdf1d931 100644 --- a/docs/cli/k3kcli_cluster.md +++ b/docs/cli/k3kcli_cluster.md @@ -1,6 +1,6 @@ ## k3kcli cluster -cluster command +K3k cluster command. ### Options @@ -17,8 +17,8 @@ cluster command ### SEE ALSO -* [k3kcli](k3kcli.md) - CLI for K3K -* [k3kcli cluster create](k3kcli_cluster_create.md) - Create new cluster -* [k3kcli cluster delete](k3kcli_cluster_delete.md) - Delete an existing cluster -* [k3kcli cluster list](k3kcli_cluster_list.md) - List all the existing cluster +* [k3kcli](k3kcli.md) - CLI for K3K. +* [k3kcli cluster create](k3kcli_cluster_create.md) - Create a new cluster. +* [k3kcli cluster delete](k3kcli_cluster_delete.md) - Delete an existing cluster. +* [k3kcli cluster list](k3kcli_cluster_list.md) - List all existing clusters. diff --git a/docs/cli/k3kcli_cluster_create.md b/docs/cli/k3kcli_cluster_create.md index 5ba47a12..7afccb21 100644 --- a/docs/cli/k3kcli_cluster_create.md +++ b/docs/cli/k3kcli_cluster_create.md @@ -1,6 +1,6 @@ ## k3kcli cluster create -Create new cluster +Create a new cluster. ``` k3kcli cluster create [flags] @@ -49,5 +49,5 @@ k3kcli cluster create [command options] NAME ### SEE ALSO -* [k3kcli cluster](k3kcli_cluster.md) - cluster command +* [k3kcli cluster](k3kcli_cluster.md) - K3k cluster command. diff --git a/docs/cli/k3kcli_cluster_delete.md b/docs/cli/k3kcli_cluster_delete.md index ee9dd4a8..4a63d5fe 100644 --- a/docs/cli/k3kcli_cluster_delete.md +++ b/docs/cli/k3kcli_cluster_delete.md @@ -1,6 +1,6 @@ ## k3kcli cluster delete -Delete an existing cluster +Delete an existing cluster. ``` k3kcli cluster delete [flags] @@ -29,5 +29,5 @@ k3kcli cluster delete [command options] NAME ### SEE ALSO -* [k3kcli cluster](k3kcli_cluster.md) - cluster command +* [k3kcli cluster](k3kcli_cluster.md) - K3k cluster command. diff --git a/docs/cli/k3kcli_cluster_list.md b/docs/cli/k3kcli_cluster_list.md index 909b1844..d1fe7f13 100644 --- a/docs/cli/k3kcli_cluster_list.md +++ b/docs/cli/k3kcli_cluster_list.md @@ -1,6 +1,6 @@ ## k3kcli cluster list -List all the existing cluster +List all existing clusters. ``` k3kcli cluster list [flags] @@ -28,5 +28,5 @@ k3kcli cluster list [command options] ### SEE ALSO -* [k3kcli cluster](k3kcli_cluster.md) - cluster command +* [k3kcli cluster](k3kcli_cluster.md) - K3k cluster command. diff --git a/docs/cli/k3kcli_kubeconfig.md b/docs/cli/k3kcli_kubeconfig.md index bf01fc6d..8c0e344d 100644 --- a/docs/cli/k3kcli_kubeconfig.md +++ b/docs/cli/k3kcli_kubeconfig.md @@ -1,6 +1,6 @@ ## k3kcli kubeconfig -Manage kubeconfig for clusters +Manage kubeconfig for clusters. ### Options @@ -17,6 +17,6 @@ Manage kubeconfig for clusters ### SEE ALSO -* [k3kcli](k3kcli.md) - CLI for K3K -* [k3kcli kubeconfig generate](k3kcli_kubeconfig_generate.md) - Generate kubeconfig for clusters +* [k3kcli](k3kcli.md) - CLI for K3K. +* [k3kcli kubeconfig generate](k3kcli_kubeconfig_generate.md) - Generate kubeconfig for clusters. diff --git a/docs/cli/k3kcli_kubeconfig_generate.md b/docs/cli/k3kcli_kubeconfig_generate.md index 3ce253b0..3594f67d 100644 --- a/docs/cli/k3kcli_kubeconfig_generate.md +++ b/docs/cli/k3kcli_kubeconfig_generate.md @@ -1,6 +1,6 @@ ## k3kcli kubeconfig generate -Generate kubeconfig for clusters +Generate kubeconfig for clusters. ``` k3kcli kubeconfig generate [flags] @@ -29,5 +29,5 @@ k3kcli kubeconfig generate [flags] ### SEE ALSO -* [k3kcli kubeconfig](k3kcli_kubeconfig.md) - Manage kubeconfig for clusters +* [k3kcli kubeconfig](k3kcli_kubeconfig.md) - Manage kubeconfig for clusters. diff --git a/docs/cli/k3kcli_policy.md b/docs/cli/k3kcli_policy.md index b3b31258..0c83d7aa 100644 --- a/docs/cli/k3kcli_policy.md +++ b/docs/cli/k3kcli_policy.md @@ -1,6 +1,6 @@ ## k3kcli policy -policy command +K3k policy command. ### Options @@ -17,8 +17,8 @@ policy command ### SEE ALSO -* [k3kcli](k3kcli.md) - CLI for K3K -* [k3kcli policy create](k3kcli_policy_create.md) - Create new policy -* [k3kcli policy delete](k3kcli_policy_delete.md) - Delete an existing policy -* [k3kcli policy list](k3kcli_policy_list.md) - List all the existing policies +* [k3kcli](k3kcli.md) - CLI for K3K. +* [k3kcli policy create](k3kcli_policy_create.md) - Create a new policy. +* [k3kcli policy delete](k3kcli_policy_delete.md) - Delete an existing policy. +* [k3kcli policy list](k3kcli_policy_list.md) - List all existing policies. diff --git a/docs/cli/k3kcli_policy_create.md b/docs/cli/k3kcli_policy_create.md index 96cfe55c..2616d796 100644 --- a/docs/cli/k3kcli_policy_create.md +++ b/docs/cli/k3kcli_policy_create.md @@ -1,6 +1,6 @@ ## k3kcli policy create -Create new policy +Create a new policy. ``` k3kcli policy create [flags] @@ -32,5 +32,5 @@ k3kcli policy create [command options] NAME ### SEE ALSO -* [k3kcli policy](k3kcli_policy.md) - policy command +* [k3kcli policy](k3kcli_policy.md) - K3k policy command. diff --git a/docs/cli/k3kcli_policy_delete.md b/docs/cli/k3kcli_policy_delete.md index 20a3b164..555344af 100644 --- a/docs/cli/k3kcli_policy_delete.md +++ b/docs/cli/k3kcli_policy_delete.md @@ -1,6 +1,6 @@ ## k3kcli policy delete -Delete an existing policy +Delete an existing policy. ``` k3kcli policy delete [flags] @@ -27,5 +27,5 @@ k3kcli policy delete [command options] NAME ### SEE ALSO -* [k3kcli policy](k3kcli_policy.md) - policy command +* [k3kcli policy](k3kcli_policy.md) - K3k policy command. diff --git a/docs/cli/k3kcli_policy_list.md b/docs/cli/k3kcli_policy_list.md index 4903d866..1538aa3a 100644 --- a/docs/cli/k3kcli_policy_list.md +++ b/docs/cli/k3kcli_policy_list.md @@ -1,6 +1,6 @@ ## k3kcli policy list -List all the existing policies +List all existing policies. ``` k3kcli policy list [flags] @@ -27,5 +27,5 @@ k3kcli policy list [command options] ### SEE ALSO -* [k3kcli policy](k3kcli_policy.md) - policy command +* [k3kcli policy](k3kcli_policy.md) - K3k policy command. diff --git a/scripts/generate-cli-docs b/scripts/generate-cli-docs new file mode 100755 index 00000000..b2baa724 --- /dev/null +++ b/scripts/generate-cli-docs @@ -0,0 +1,42 @@ +#!/bin/bash + +set -eou pipefail + +DOCS_DIR=./docs/cli + +# Generate the raw markdown files +go run $DOCS_DIR/genclidoc.go + +echo "Converting Markdown documentation to asciidoc" + +pandoc --from markdown --to asciidoc --lua-filter=$DOCS_DIR/convert.lua $DOCS_DIR/k3kcli.md > $DOCS_DIR/k3kcli.adoc +echo "" >> $DOCS_DIR/k3kcli.adoc + +# We use an explicit list of files to keep a stable ordering +SUBCOMMAND_FILES=( + "$DOCS_DIR/k3kcli_cluster.md" + "$DOCS_DIR/k3kcli_cluster_create.md" + "$DOCS_DIR/k3kcli_cluster_delete.md" + "$DOCS_DIR/k3kcli_cluster_list.md" + "$DOCS_DIR/k3kcli_kubeconfig.md" + "$DOCS_DIR/k3kcli_kubeconfig_generate.md" + "$DOCS_DIR/k3kcli_policy.md" + "$DOCS_DIR/k3kcli_policy_create.md" + "$DOCS_DIR/k3kcli_policy_delete.md" + "$DOCS_DIR/k3kcli_policy_list.md" +) + +# Check for newly added doc files +EXPECTED_COUNT=${#SUBCOMMAND_FILES[@]} +ACTUAL_COUNT=$(ls -1 $DOCS_DIR/k3kcli_*.md | wc -l) + +if [ "$EXPECTED_COUNT" -ne "$ACTUAL_COUNT" ]; then + echo "ERROR: File count mismatch!" + echo "Expected $EXPECTED_COUNT files in the array, but found $ACTUAL_COUNT on disk." + echo "Please update the SUBCOMMAND_FILES array in $0" + exit 1 +fi + +pandoc --from markdown --to asciidoc --lua-filter=$DOCS_DIR/convert.lua "${SUBCOMMAND_FILES[@]}">> $DOCS_DIR/k3kcli.adoc + +echo "Asciidoc documentation generated at $DOCS_DIR/k3kcli.adoc"