add action doc (#1032)

<!-- markdownlint-disable MD041 -->
#### What this PR does / why we need it
Add documentation to command `ocm execute action`.

#### Which issue(s) this PR fixes
<!--
Usage: `Fixes #<issue number>`, or `Fixes (paste link of issue)`.
-->

api/datacontext/action/api/registry.go

@@ -5,6 +5,7 @@ import (
 	"sync"
 
 	"github.com/mandelsoft/goutils/errors"
+	"github.com/mandelsoft/goutils/maputils"
 	"golang.org/x/exp/slices"
 
 	"ocm.software/ocm/api/utils"
@@ -26,6 +27,7 @@ type ActionTypeRegistry interface {
 	DecodeActionResult(data []byte, unmarshaler runtime.Unmarshaler) (ActionResult, error)
 	EncodeActionResult(spec ActionResult, marshaler runtime.Marshaler) ([]byte, error)
 
+	GetActionNames() []string
 	GetAction(name string) Action
 	SupportedActionVersions(name string) []string
 
@@ -161,6 +163,12 @@ func (r *actionRegistry) RegisterActionType(typ ActionType) error {
 	return nil
 }
 
+func (r *actionRegistry) GetActionNames() []string {
+	r.lock.Lock()
+	defer r.lock.Unlock()
+	return maputils.OrderedKeys(r.actions)
+}
+
 func (r *actionRegistry) GetAction(name string) Action {
 	r.lock.Lock()
 	defer r.lock.Unlock()

api/datacontext/action/api/utils.go

@@ -1,6 +1,8 @@
 package api
 
 import (
+	"ocm.software/ocm/api/utils"
+	common "ocm.software/ocm/api/utils/misc"
 	"ocm.software/ocm/api/utils/runtime"
 )
 
@@ -36,3 +38,26 @@ func (a *actionType) SpecificationType() ActionSpecType {
 func (a *actionType) ResultType() ActionResultType {
 	return a.restype
 }
+
+func Usage(reg ActionTypeRegistry) string {
+	p, buf := common.NewBufferedPrinter()
+	for _, n := range reg.GetActionNames() {
+		a := reg.GetAction(n)
+		p.Printf("- Name: %s\n", n)
+		if a.Description() != "" {
+			p.Printf("%s\n", utils.IndentLines(a.Description(), "    "))
+		}
+		if a.Usage() != "" {
+			p.Printf("\n%s\n", utils.IndentLines(a.Usage(), "    "))
+		}
+		p := p.AddGap("  ")
+
+		if len(a.ConsumerAttributes()) > 0 {
+			p.Printf("Possible Consumer Attributes:\n")
+			for _, a := range a.ConsumerAttributes() {
+				p.Printf("- <code>%s</code>\n", a)
+			}
+		}
+	}
+	return buf.String()
+}

cmds/ocm/commands/misccmds/action/execute/cmd.go

@@ -11,6 +11,7 @@ import (
 	clictx "ocm.software/ocm/api/cli"
 	"ocm.software/ocm/api/credentials"
 	"ocm.software/ocm/api/datacontext/action"
+	"ocm.software/ocm/api/datacontext/action/api"
 	utils2 "ocm.software/ocm/api/utils"
 	common "ocm.software/ocm/api/utils/misc"
 	"ocm.software/ocm/api/utils/out"
@@ -54,11 +55,13 @@ func (o *Command) ForName(name string) *cobra.Command {
 		Args:  cobra.MinimumNArgs(1),
 		Long: `
 Execute an action extension for a given action specification. The specification
-show be a JSON or YAML argument.
+should be a JSON or YAML argument.
 
 Additional properties settings can be used to describe a consumer id
 to retrieve credentials for.
-`,
+
+The following actions are supported:
+` + api.Usage(api.DefaultRegistry()),
 		Example: `
 $ ocm execute action '{ "type": "oci.repository.prepare/v1", "hostname": "...", "repository": "..."}'
 `,

docs/reference/ocm_execute_action.md

@@ -18,11 +18,27 @@ ocm execute action [<options>] <action spec> {<cred>=<value>}
 ### Description
 
 Execute an action extension for a given action specification. The specification
-show be a JSON or YAML argument.
+should be a JSON or YAML argument.
 
 Additional properties settings can be used to describe a consumer id
 to retrieve credentials for.
 
+The following actions are supported:
+- Name: oci.repository.prepare
+    Prepare the usage of a repository in an OCI registry.
+
+    The hostname of the target repository is used as selector. The action should
+    assure, that the requested repository is available on the target OCI registry.
+
+    Spec version v1 uses the following specification fields:
+    - <code>hostname</code> *string*: The  hostname of the OCI registry.
+    - <code>repository</code> *string*: The OCI repository name.
+
+  Possible Consumer Attributes:
+  - <code>hostname</code>
+  - <code>port</code>
+  - <code>pathprefix</code>
+
 ### Examples
 
 ```bash