From 39aac8e9d8f785c98b6b718c29f10b51c0e6b6eb Mon Sep 17 00:00:00 2001
From: Jaime Soriano Pastor <jaime.soriano@elastic.co>
Date: Tue, 4 Apr 2023 16:34:37 +0200
Subject: [PATCH] Include short description of subcommands in README when long
 is not available

---
 README.md                   | 21 ++++++++++-----------
 cmd/changelog.go            |  3 +--
 tools/readme/main.go        | 15 +++++++++++----
 tools/readme/subcmd.md.tmpl |  2 +-
 4 files changed, 23 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 1ef5f54783..b624684919 100644
--- a/README.md
+++ b/README.md
@@ -152,7 +152,6 @@ last entry in the current version
 Alternatively, you can start a new version indicating the specific version, or if it should
 be the next major, minor or patch version.
 
-
 ### `elastic-package check`
 
 _Context: package_
@@ -273,25 +272,25 @@ User profiles are not overwritten on upgrade of elastic-stack, and can be freely
 
 _Context: global_
 
-
+Create a new profile.
 
 ### `elastic-package profiles delete`
 
 _Context: global_
 
-
+Delete a profile.
 
 ### `elastic-package profiles list`
 
 _Context: global_
 
-
+List available profiles.
 
 ### `elastic-package profiles use`
 
 _Context: global_
 
-
+Sets the profile to use when no other is specified.
 
 ### `elastic-package promote`
 
@@ -343,7 +342,7 @@ The command manages lifecycle of the service stack defined for the package ("_de
 
 _Context: package_
 
-
+Boot up the stack.
 
 ### `elastic-package stack`
 
@@ -359,25 +358,25 @@ For details on how to connect the service with the Elastic stack, see the [servi
 
 _Context: global_
 
-
+Take down the stack.
 
 ### `elastic-package stack dump`
 
 _Context: global_
 
-
+Dump stack data for debug purposes.
 
 ### `elastic-package stack shellinit`
 
 _Context: global_
 
-
+Export environment variables.
 
 ### `elastic-package stack status`
 
 _Context: global_
 
-
+Show status of the stack services.
 
 ### `elastic-package stack up`
 
@@ -397,7 +396,7 @@ For details on how to connect the service with the Elastic stack, see the [servi
 
 _Context: global_
 
-
+Update the stack to the most recent versions.
 
 ### `elastic-package status [package]`
 
diff --git a/cmd/changelog.go b/cmd/changelog.go
index c97dc4c968..c2d3c1bea3 100644
--- a/cmd/changelog.go
+++ b/cmd/changelog.go
@@ -29,8 +29,7 @@ The entry added will include the given description, type and link. It is added o
 last entry in the current version
 
 Alternatively, you can start a new version indicating the specific version, or if it should
-be the next major, minor or patch version.
-`
+be the next major, minor or patch version.`
 
 func setupChangelogCommand() *cobraext.Command {
 	addChangelogCmd := &cobra.Command{
diff --git a/tools/readme/main.go b/tools/readme/main.go
index b1def9c5fd..0c6e895d3b 100644
--- a/tools/readme/main.go
+++ b/tools/readme/main.go
@@ -58,11 +58,18 @@ func generateCommandsDoc(cmdTmpl *template.Template, subCommandTemplate *templat
 		}
 		for _, subCommand := range cmd.Commands() {
 			log.Printf("generating command doc for %s %s...\n", cmd.Name(), subCommand.Name())
+			description := subCommand.Long
+			if description == "" {
+				description = subCommand.Short
+			}
+			if !strings.HasSuffix(strings.TrimSpace(description), ".") {
+				description = description + "."
+			}
 			templateData := map[string]any{
-				"CmdName":    cmd.Name(),
-				"SubCmdName": subCommand.Name(),
-				"Context":    cmd.Context(),
-				"Long":       subCommand.Long,
+				"CmdName":     cmd.Name(),
+				"SubCmdName":  subCommand.Name(),
+				"Context":     cmd.Context(),
+				"Description": description,
 			}
 			if err := subCommandTemplate.Execute(&cmdsDoc, templateData); err != nil {
 				log.Fatal(errors.Wrapf(err, "writing documentation for command '%s %s' failed", cmd.Name(), subCommand.Name()))
diff --git a/tools/readme/subcmd.md.tmpl b/tools/readme/subcmd.md.tmpl
index ab586c7728..2fb36c6ff4 100644
--- a/tools/readme/subcmd.md.tmpl
+++ b/tools/readme/subcmd.md.tmpl
@@ -2,5 +2,5 @@
 
 _Context: {{.Context}}_
 
-{{.Long}}
+{{.Description}}