Refactor docs generator: add longMD into Annotations

werf · Oct 5, 2022 · 5261f5c · 5261f5c
1 parent 340749f
commit 5261f5c
Show file tree

Hide file tree

Showing 31 changed files with 41 additions and 63 deletions.
diff --git a/cmd/werf/build/main.go b/cmd/werf/build/main.go
@@ -45,6 +45,7 @@ func NewCmd(ctx context.Context) *cobra.Command {
 		DisableFlagsInUseLine: true,
 		Annotations: map[string]string{
 			common.CmdEnvAnno: common.EnvsDescription(common.WerfDebugAnsibleArgs),
+			common.DocsLongMD: GetBuildDocs().LongMD,
 		},
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()

diff --git a/cmd/werf/bundle/export/export.go b/cmd/werf/bundle/export/export.go
@@ -47,6 +47,7 @@ func NewCmd(ctx context.Context) *cobra.Command {
 		DisableFlagsInUseLine: true,
 		Annotations: map[string]string{
 			common.CmdEnvAnno: common.EnvsDescription(),
+			common.DocsLongMD: GetBundleExportDocs().LongMD,
 		},
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()

diff --git a/cmd/werf/bundle/publish/publish.go b/cmd/werf/bundle/publish/publish.go
@@ -49,6 +49,7 @@ func NewCmd(ctx context.Context) *cobra.Command {
 		DisableFlagsInUseLine: true,
 		Annotations: map[string]string{
 			common.CmdEnvAnno: common.EnvsDescription(),
+			common.DocsLongMD: GetBundlePublishDocs().LongMD,
 		},
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()

diff --git a/cmd/werf/cleanup/cleanup.go b/cmd/werf/cleanup/cleanup.go
@@ -36,6 +36,9 @@ func NewCmd(ctx context.Context) *cobra.Command {
 		Short:                 "Cleanup project images in the container registry",
 		Long:                  common.GetLongCommandDescription(GetCleanupDocs().Long),
 		Example:               `  $ werf cleanup --repo registry.mydomain.com/myproject/werf`,
+		Annotations: map[string]string{
+			common.DocsLongMD: GetCleanupDocs().LongMD,
+		},
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 

diff --git a/cmd/werf/common/envs.go b/cmd/werf/common/envs.go
@@ -14,14 +14,16 @@ const (
 	CmdEnvAnno                  string = "environment"
 	DisableOptionsInUseLineAnno string = "disableOptionsInUseLine"
 
+	DocsLongMD string = "docsLongMD"
+
 	WerfDebugAnsibleArgs Env = "WERF_DEBUG_ANSIBLE_ARGS"
 	WerfSecretKey        Env = "WERF_SECRET_KEY"
 	WerfOldSecretKey     Env = "WERF_OLD_SECRET_KEY"
 )
 
 var envDescription = map[Env]string{
 	WerfDebugAnsibleArgs: "Pass specified cli args to ansible ($ANSIBLE_ARGS)",
-	WerfSecretKey: `Use specified secret key to extract secrets for the deploy. Recommended way to set secret key in CI-system. 
+	WerfSecretKey: `Use specified secret key to extract secrets for the deploy. Recommended way to set secret key in CI-system.
 
 Secret key also can be defined in files:
 * ~/.werf/global_secret_key (globally),

diff --git a/cmd/werf/compose/main.go b/cmd/werf/compose/main.go
@@ -131,6 +131,7 @@ func newCmd(ctx context.Context, composeCmdName string, options *newCmdOptions)
 		DisableFlagsInUseLine: true,
 		Annotations: map[string]string{
 			common.DisableOptionsInUseLineAnno: "1",
+			common.DocsLongMD:                  GetComposeDocs(short).LongMD,
 		},
 		Example: options.Example,
 		RunE: func(cmd *cobra.Command, args []string) error {

diff --git a/cmd/werf/converge/converge.go b/cmd/werf/converge/converge.go
@@ -74,6 +74,7 @@ werf converge --repo registry.mydomain.com/web --env production`,
 		DisableFlagsInUseLine: true,
 		Annotations: map[string]string{
 			common.CmdEnvAnno: common.EnvsDescription(common.WerfDebugAnsibleArgs, common.WerfSecretKey),
+			common.DocsLongMD: GetConvergeDocs().LongMD,
 		},
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()

diff --git a/cmd/werf/dismiss/dismiss.go b/cmd/werf/dismiss/dismiss.go
@@ -51,6 +51,9 @@ func NewCmd(ctx context.Context) *cobra.Command {
   # Dismiss project using specified helm release name and namespace
   $ werf dismiss --release myrelease --namespace myns`,
 		DisableFlagsInUseLine: true,
+		Annotations: map[string]string{
+			common.DocsLongMD: GetDismissDocs().LongMD,
+		},
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 

diff --git a/cmd/werf/docs/md_docs.go b/cmd/werf/docs/md_docs.go
@@ -3,7 +3,6 @@ package docs
 import (
 	"bytes"
 	"fmt"
-	"html"
 	"io"
 	"io/ioutil"
 	"os"
@@ -13,20 +12,8 @@ import (
 	"github.com/spf13/cobra"
 	"mvdan.cc/xurls"
 
-	"github.com/werf/werf/cmd/werf/build"
-	"github.com/werf/werf/cmd/werf/bundle/export"
-	"github.com/werf/werf/cmd/werf/bundle/publish"
-	"github.com/werf/werf/cmd/werf/cleanup"
 	"github.com/werf/werf/cmd/werf/common"
 	"github.com/werf/werf/cmd/werf/common/templates"
-	"github.com/werf/werf/cmd/werf/compose"
-	"github.com/werf/werf/cmd/werf/converge"
-	"github.com/werf/werf/cmd/werf/dismiss"
-	export2 "github.com/werf/werf/cmd/werf/export"
-	"github.com/werf/werf/cmd/werf/kube_run"
-	"github.com/werf/werf/cmd/werf/purge"
-	"github.com/werf/werf/cmd/werf/render"
-	"github.com/werf/werf/cmd/werf/run"
 )
 
 func printOptions(buf *bytes.Buffer, cmd *cobra.Command) error {
@@ -358,38 +345,9 @@ func writeShortCommandMarkdownPartial(cmd *cobra.Command, dir string) error {
 }
 
 func getLongFromCommand(cmd *cobra.Command) string {
-	switch cmd.Short {
-	case "Build and push images, then deploy application into Kubernetes":
-		return html.EscapeString(converge.GetConvergeDocs().LongMD)
-	case "Delete application from Kubernetes":
-		return html.EscapeString(dismiss.GetDismissDocs().LongMD)
-	case "Export bundle":
-		return html.EscapeString(export.GetBundleExportDocs().LongMD)
-	case "Publish bundle":
-		return html.EscapeString(publish.GetBundlePublishDocs().LongMD)
-	case "Cleanup project images in the container registry":
-		return html.EscapeString(cleanup.GetCleanupDocs().LongMD)
-	case "Purge all project images in the container registry":
-		return html.EscapeString(purge.GetPurgeDocs().LongMD)
-	case "Build images":
-		return html.EscapeString(build.GetBuildDocs().LongMD)
-	case "Export images":
-		return html.EscapeString(export2.GetExportDocs().LongMD)
-	case "Run container for project image":
-		return html.EscapeString(run.GetRunDocs().LongMD)
-	case "Run container for project image in Kubernetes":
-		return html.EscapeString(kube_run.GetKubeRunDocs().LongMD)
-	case "Run docker-compose config command with forwarded image names.":
-		return compose.GetComposeDocs(cmd.Short).LongMD
-	case "Run docker-compose down command with forwarded image names.":
-		return compose.GetComposeDocs(cmd.Short).LongMD
-	case "Run docker-compose run command with forwarded image names.":
-		return compose.GetComposeDocs(cmd.Short).LongMD
-	case "Run docker-compose up command with forwarded image names.":
-		return compose.GetComposeDocs(cmd.Short).LongMD
-	case "Render Kubernetes templates":
-		return html.EscapeString(render.GetRenderDocs().LongMD)
-	default:
+	if ann, ok := cmd.Annotations[common.DocsLongMD]; ok {
+		return ann
+	} else {
 		if len(cmd.Long) == 0 {
 			return cmd.Short
 		} else {

diff --git a/cmd/werf/export/export.go b/cmd/werf/export/export.go
@@ -42,6 +42,7 @@ func NewExportCmd(ctx context.Context) *cobra.Command {
   $ werf export --tag=index.docker.io/company/project:%image%-latest --tag=ghcr.io/company/project/%image%:latest`,
 		Annotations: map[string]string{
 			common.DisableOptionsInUseLineAnno: "1",
+			common.DocsLongMD:                  GetExportDocs().LongMD,
 		},
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()

diff --git a/cmd/werf/kube_run/kube_run.go b/cmd/werf/kube_run/kube_run.go
@@ -101,6 +101,7 @@ func NewCmd(ctx context.Context) *cobra.Command {
 `,
 		Annotations: map[string]string{
 			common.DisableOptionsInUseLineAnno: "1",
+			common.DocsLongMD:                  GetKubeRunDocs().LongMD,
 		},
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()

diff --git a/cmd/werf/kube_run/kube_run_docs.go b/cmd/werf/kube_run/kube_run_docs.go
@@ -7,7 +7,7 @@ func GetKubeRunDocs() structs.DocsStruct {
 
 	docs.Long = `Run container in Kubernetes for specified project image from werf.yaml (build if needed).`
 
-	docs.LongMD = "Run container in Kubernetes for specified project image from `werf.yaml` (build if needed)"
+	docs.LongMD = "Run container in Kubernetes for specified project image from `werf.yaml` (build if needed)."
 
 	return docs
 }
diff --git a/cmd/werf/purge/purge.go b/cmd/werf/purge/purge.go
@@ -28,6 +28,9 @@ func NewCmd(ctx context.Context) *cobra.Command {
 		DisableFlagsInUseLine: true,
 		Short:                 "Purge all project images in the container registry",
 		Long:                  common.GetLongCommandDescription(GetPurgeDocs().Long),
+		Annotations: map[string]string{
+			common.DocsLongMD: GetPurgeDocs().LongMD,
+		},
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 

diff --git a/cmd/werf/render/render.go b/cmd/werf/render/render.go
@@ -56,6 +56,7 @@ func NewCmd(ctx context.Context) *cobra.Command {
 		DisableFlagsInUseLine: true,
 		Annotations: map[string]string{
 			common.CmdEnvAnno: common.EnvsDescription(common.WerfDebugAnsibleArgs, common.WerfSecretKey),
+			common.DocsLongMD: GetRenderDocs().LongMD,
 		},
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()

diff --git a/cmd/werf/run/run.go b/cmd/werf/run/run.go
@@ -67,6 +67,7 @@ func NewCmd(ctx context.Context) *cobra.Command {
   docker run -ti --rm image-stage-test:1ffe83860127e68e893b6aece5b0b7619f903f8492a285c6410371c87018c6a0 /bin/sh`,
 		Annotations: map[string]string{
 			common.DisableOptionsInUseLineAnno: "1",
+			common.DocsLongMD:                  GetRunDocs().LongMD,
 		},
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()

diff --git a/docs/_includes/reference/cli/werf_bundle_render.md b/docs/_includes/reference/cli/werf_bundle_render.md
@@ -16,7 +16,7 @@ werf bundle render [options]
 
 ```shell
   $WERF_SECRET_KEY  Use specified secret key to extract secrets for the deploy. Recommended way to  
-                    set secret key in CI-system. 
+                    set secret key in CI-system.
 
                     Secret key also can be defined in files:
                     * ~/.werf/global_secret_key (globally),

diff --git a/docs/_includes/reference/cli/werf_converge.md b/docs/_includes/reference/cli/werf_converge.md
@@ -30,7 +30,7 @@ werf converge --repo registry.mydomain.com/web --env production
 ```shell
   $WERF_DEBUG_ANSIBLE_ARGS  Pass specified cli args to ansible ($ANSIBLE_ARGS)
   $WERF_SECRET_KEY          Use specified secret key to extract secrets for the deploy. Recommended 
-                            way to set secret key in CI-system. 
+                            way to set secret key in CI-system.
 
                             Secret key also can be defined in files:
                             * ~/.werf/global_secret_key (globally),

diff --git a/docs/_includes/reference/cli/werf_export.md b/docs/_includes/reference/cli/werf_export.md
@@ -8,7 +8,7 @@ Export images to an arbitrary repository according to a template specified by th
 The tag may contain the following shortcuts:
 - `image`, `image_slug` or `image_safe_slug` to use the image name (necessary if there is more than one image in the werf config);
 - `image_content_based_tag` to use a content-based tag.
-All meta-information related to werf is removed from the exported images, and then images are completely under the user&#39;s responsibility.
+All meta-information related to werf is removed from the exported images, and then images are completely under the user's responsibility.
 
 {{ header }} Syntax
 

diff --git a/docs/_includes/reference/cli/werf_helm_get_autogenerated_values.md b/docs/_includes/reference/cli/werf_helm_get_autogenerated_values.md
@@ -17,7 +17,7 @@ werf helm get-autogenerated-values [IMAGE_NAME...] [options]
 
 ```shell
   $WERF_SECRET_KEY  Use specified secret key to extract secrets for the deploy. Recommended way to  
-                    set secret key in CI-system. 
+                    set secret key in CI-system.
 
                     Secret key also can be defined in files:
                     * ~/.werf/global_secret_key (globally),

diff --git a/docs/_includes/reference/cli/werf_helm_secret_decrypt.md b/docs/_includes/reference/cli/werf_helm_secret_decrypt.md
@@ -29,7 +29,7 @@ werf helm secret decrypt [options]
 
 ```shell
   $WERF_SECRET_KEY  Use specified secret key to extract secrets for the deploy. Recommended way to  
-                    set secret key in CI-system. 
+                    set secret key in CI-system.
 
                     Secret key also can be defined in files:
                     * ~/.werf/global_secret_key (globally),

diff --git a/docs/_includes/reference/cli/werf_helm_secret_encrypt.md b/docs/_includes/reference/cli/werf_helm_secret_encrypt.md
@@ -28,7 +28,7 @@ werf helm secret encrypt [options]
 
 ```shell
   $WERF_SECRET_KEY  Use specified secret key to extract secrets for the deploy. Recommended way to  
-                    set secret key in CI-system. 
+                    set secret key in CI-system.
 
                     Secret key also can be defined in files:
                     * ~/.werf/global_secret_key (globally),

diff --git a/docs/_includes/reference/cli/werf_helm_secret_file_decrypt.md b/docs/_includes/reference/cli/werf_helm_secret_file_decrypt.md
@@ -27,7 +27,7 @@ werf helm secret file decrypt [FILE_PATH] [options]
 
 ```shell
   $WERF_SECRET_KEY  Use specified secret key to extract secrets for the deploy. Recommended way to  
-                    set secret key in CI-system. 
+                    set secret key in CI-system.
 
                     Secret key also can be defined in files:
                     * ~/.werf/global_secret_key (globally),

diff --git a/docs/_includes/reference/cli/werf_helm_secret_file_edit.md b/docs/_includes/reference/cli/werf_helm_secret_file_edit.md
@@ -23,7 +23,7 @@ werf helm secret file edit FILE_PATH [options]
 
 ```shell
   $WERF_SECRET_KEY  Use specified secret key to extract secrets for the deploy. Recommended way to  
-                    set secret key in CI-system. 
+                    set secret key in CI-system.
 
                     Secret key also can be defined in files:
                     * ~/.werf/global_secret_key (globally),

diff --git a/docs/_includes/reference/cli/werf_helm_secret_file_encrypt.md b/docs/_includes/reference/cli/werf_helm_secret_file_encrypt.md
@@ -23,7 +23,7 @@ werf helm secret file encrypt [FILE_PATH] [options]
 
 ```shell
   $WERF_SECRET_KEY  Use specified secret key to extract secrets for the deploy. Recommended way to  
-                    set secret key in CI-system. 
+                    set secret key in CI-system.
 
                     Secret key also can be defined in files:
                     * ~/.werf/global_secret_key (globally),

diff --git a/docs/_includes/reference/cli/werf_helm_secret_rotate_secret_key.md b/docs/_includes/reference/cli/werf_helm_secret_rotate_secret_key.md
@@ -23,7 +23,7 @@ werf helm secret rotate-secret-key [EXTRA_SECRET_VALUES_FILE_PATH...] [options]
 
 ```shell
   $WERF_SECRET_KEY      Use specified secret key to extract secrets for the deploy. Recommended way 
-                        to set secret key in CI-system. 
+                        to set secret key in CI-system.
 
                         Secret key also can be defined in files:
                         * ~/.werf/global_secret_key (globally),

diff --git a/docs/_includes/reference/cli/werf_helm_secret_values_decrypt.md b/docs/_includes/reference/cli/werf_helm_secret_values_decrypt.md
@@ -32,7 +32,7 @@ werf helm secret values decrypt [FILE_PATH] [options]
 
 ```shell
   $WERF_SECRET_KEY  Use specified secret key to extract secrets for the deploy. Recommended way to  
-                    set secret key in CI-system. 
+                    set secret key in CI-system.
 
                     Secret key also can be defined in files:
                     * ~/.werf/global_secret_key (globally),

diff --git a/docs/_includes/reference/cli/werf_helm_secret_values_edit.md b/docs/_includes/reference/cli/werf_helm_secret_values_edit.md
@@ -23,7 +23,7 @@ werf helm secret values edit FILE_PATH [options]
 
 ```shell
   $WERF_SECRET_KEY  Use specified secret key to extract secrets for the deploy. Recommended way to  
-                    set secret key in CI-system. 
+                    set secret key in CI-system.
 
                     Secret key also can be defined in files:
                     * ~/.werf/global_secret_key (globally),

diff --git a/docs/_includes/reference/cli/werf_helm_secret_values_encrypt.md b/docs/_includes/reference/cli/werf_helm_secret_values_encrypt.md
@@ -23,7 +23,7 @@ werf helm secret values encrypt [FILE_PATH] [options]
 
 ```shell
   $WERF_SECRET_KEY  Use specified secret key to extract secrets for the deploy. Recommended way to  
-                    set secret key in CI-system. 
+                    set secret key in CI-system.
 
                     Secret key also can be defined in files:
                     * ~/.werf/global_secret_key (globally),

diff --git a/docs/_includes/reference/cli/werf_kube_run.md b/docs/_includes/reference/cli/werf_kube_run.md
@@ -3,7 +3,7 @@
 {% else %}
 {% assign header = "###" %}
 {% endif %}
-Run container in Kubernetes for specified project image from `werf.yaml` (build if needed)
+Run container in Kubernetes for specified project image from `werf.yaml` (build if needed).
 
 {{ header }} Syntax
 

diff --git a/docs/_includes/reference/cli/werf_kubectl_get.md b/docs/_includes/reference/cli/werf_kubectl_get.md
@@ -14,7 +14,7 @@ Use "kubectl api-resources" for a complete list of supported resources.
 {{ header }} Syntax
 
 ```shell
-werf kubectl get [(-o|--output=)json|yaml|name|go-template|go-template-file|template|templatefile|jsonpath|jsonpath-as-json|jsonpath-file|custom-columns|custom-columns-file|wide] (TYPE[.VERSION][.GROUP] [NAME | -l label] | TYPE[.VERSION][.GROUP]/NAME ...) [flags] [options]
+werf kubectl get [(-o|--output=)json|yaml|name|go-template|go-template-file|template|templatefile|jsonpath|jsonpath-as-json|jsonpath-file|custom-columns-file|custom-columns|wide] (TYPE[.VERSION][.GROUP] [NAME | -l label] | TYPE[.VERSION][.GROUP]/NAME ...) [flags] [options]
 ```
 
 {{ header }} Examples

diff --git a/docs/_includes/reference/cli/werf_render.md b/docs/_includes/reference/cli/werf_render.md
@@ -16,7 +16,7 @@ werf render [IMAGE_NAME...] [options]
 ```shell
   $WERF_DEBUG_ANSIBLE_ARGS  Pass specified cli args to ansible ($ANSIBLE_ARGS)
   $WERF_SECRET_KEY          Use specified secret key to extract secrets for the deploy. Recommended 
-                            way to set secret key in CI-system. 
+                            way to set secret key in CI-system.
 
                             Secret key also can be defined in files:
                             * ~/.werf/global_secret_key (globally),