Format detailed help using markdown and auto-generate reference docs

cmd/crossplane/config/config.go

@@ -17,6 +17,11 @@ limitations under the License.
 // Package config contains the `crossplane config` subcommands.
 package config
 
+import _ "embed"
+
+//go:embed help/config.md
+var helpDetail string
+
 // ConfigPath is the resolved config file path. It is bound by main so that
 // subcommands can receive it as a Run() argument. Using a typed alias keeps
 // the binding distinct from any other string value Kong may know about.
@@ -31,19 +36,5 @@ type Cmd struct {
 
 // Help returns the extended help for the config command.
 func (c *Cmd) Help() string {
-	return `
-Manage the crossplane CLI configuration file.
-
-The config file location is, in priority order:
-  1. The --config flag.
-  2. The CROSSPLANE_CONFIG environment variable.
-  3. $XDG_CONFIG_HOME/crossplane/config.yaml (or ~/.config/crossplane/config.yaml).
-
-Examples:
-  # Show the current effective config.
-  crossplane config view
-
-  # Enable alpha commands.
-  crossplane config set features.enableAlpha true
-`
+	return helpDetail
 }

cmd/crossplane/config/help/config.md

@@ -0,0 +1,20 @@
+The `config` command manages the configuration file for the `crossplane`
+CLI. The config file location is, in priority order:
+
+1. The `--config` flag.
+2. The `CROSSPLANE_CONFIG` environment variable.
+3. `$XDG_CONFIG_HOME/crossplane/config.yaml` (or `~/.config/crossplane/config.yaml`).
+
+## Examples
+
+Show the current effective config:
+
+```shell
+crossplane config view
+```
+
+Enable alpha commands:
+
+```shell
+crossplane config set features.enableAlpha true
+```

cmd/crossplane/convert/compositionenvironment/cmd.go

@@ -31,8 +31,13 @@ import (
 	"github.com/crossplane/crossplane-runtime/v2/pkg/errors"
 
 	commonIO "github.com/crossplane/cli/v2/cmd/crossplane/convert/io"
+
+	_ "embed"
 )
 
+//go:embed help/composition-environment.md
+var helpDetail string
+
 // Cmd arguments and flags for converting a Composition to use function-environment-configs.
 type Cmd struct {
 	// Arguments.
@@ -48,26 +53,7 @@ type Cmd struct {
 
 // Help returns help message for the migrate composition-environment command.
 func (c *Cmd) Help() string {
-	return `
-This command converts a Crossplane Composition to use function-environment-configs, if needed.
-
-It adds a function pipeline step using crossplane-contrib/function-environment-configs, if needed.
-By default it'll reference the function as function-environment-configs, but it can be overridden
-with the -f flag.
-
-Examples:
-
-  # Convert an existing Composition (Pipeline mode) leveraging native
-  # Composition Environment to use function-environment-configs.
-  crossplane composition convert composition-environment composition.yaml -o composition-environment.yaml
-
-  # Use a different functionRef and output to stdout.
-  crossplane composition convert composition-environment composition.yaml --function-environment-configs-ref local-function-environment-configs
-
-  # Stdin to stdout.
-  cat composition.yaml | ./crossplane composition convert composition-environment
-
-`
+	return helpDetail
 }
 
 // AfterApply implements kong.AfterApply.

cmd/crossplane/convert/compositionenvironment/help/composition-environment.md

@@ -0,0 +1,31 @@
+The `composition convert composition-environment` command converts a Crossplane
+Composition to use `function-environment-configs` in place of native Composition
+Environments, which were removed in Crossplane v1.18.
+
+It adds a function pipeline step using
+`crossplane-contrib/function-environment-configs` if needed. By default the
+function is referenced as `function-environment-configs`, but this can be
+overridden with `--function-environment-configs-ref`.
+
+## Examples
+
+Convert an existing pipeline mode Composition using native Composition
+Environment to `function-environment-configs`:
+
+```shell
+crossplane composition convert composition-environment composition.yaml \
+  -o composition-environment.yaml
+```
+
+Use a different functionRef and output to stdout:
+
+```shell
+crossplane composition convert composition-environment composition.yaml \
+  --function-environment-configs-ref=local-function-environment-configs
+```
+
+Read a composition from stdin and output the updated composition on stdout:
+
+```shell
+cat composition.yaml | crossplane composition convert composition-environment
+```

cmd/crossplane/convert/convert.go

@@ -20,24 +20,19 @@ package convert
 
 import (
 	"github.com/crossplane/cli/v2/cmd/crossplane/convert/compositionenvironment"
+
+	_ "embed"
 )
 
+//go:embed help/convert.md
+var helpDetail string
+
 // Cmd converts a Crossplane resource to a newer version or a different kind.
 type Cmd struct {
 	CompositionEnvironment compositionenvironment.Cmd `cmd:"" help:"Convert a Pipeline Composition to use function-environment-configs."`
 }
 
 // Help returns help message for the migrate command.
 func (c *Cmd) Help() string {
-	return `
-This command converts a Crossplane resource to a newer version or a different kind.
-
-Currently supported conversions:
-  * native Composition Environment -> function-environment-configs
-
-Examples:
-  # Convert an existing Composition to use function-environment-configs instead of native Composition Environment,
-  # requires the composition to be in Pipeline mode already.
-  crossplane composition convert composition-environment composition.yaml -o composition-environment.yaml
-`
+	return helpDetail
 }

cmd/crossplane/convert/help/convert.md

@@ -0,0 +1,6 @@
+The `composition convert` command converts a Crossplane composition to use a
+different version or migrate away from features that are no longer supported.
+
+The currently supported conversions are:
+
+- Native Composition Environment → `function-environment-configs`

cmd/crossplane/docs-templates/command-reference.md.tmpl

@@ -0,0 +1,45 @@
+---
+weight: 50
+title: Command Reference
+description: "Command reference for the Crossplane CLI"
+---
+
+<!-- This file is generated by `crossplane generate-docs`. Do not edit by hand. -->
+
+This documentation is for the `crossplane` CLI [[ .Version ]].
+
+[[ range .Commands ]]
+<!-- vale Google.Headings = NO -->
+<!-- vale Microsoft.Headings = NO -->
+[[ .Heading ]] [[ .FullPath ]]
+<!-- vale Google.Headings = YES -->
+<!-- vale Microsoft.Headings = YES -->
+
+[[ if .Help ]][[ .Help ]][[ end ]]
+
+[[ if .Detail ]][[ .Detail ]][[ end ]]
+
+[[ .SubHeading ]] Usage
+
+```
+crossplane [[ .Summary ]]
+```
+[[- if .Positional ]]
+[[ .SubHeading ]] Arguments
+
+{{< table "table table-sm table-striped" >}}
+| Argument | Description |
+|----------|-------------|
+[[ range .Positional ]]| `[[ .Display ]]` | [[ if not .Required ]]*(optional)* [[ end ]][[ .Help ]] |
+[[ end ]]{{< /table >}}
+[[ end ]]
+[[- if .Flags ]]
+[[ .SubHeading ]] Flags
+
+{{< table "table table-sm table-striped" >}}
+| Short flag | Long flag | Description |
+|------------|-----------|-------------|
+[[ range .Flags ]]| [[ if .Short ]]`[[ .Short ]]`[[ end ]] | `[[ .Long ]]` | [[ if .Required ]]**Required.** [[ end ]][[ .Help ]] |
+[[ end ]]{{< /table >}}
+[[ end ]]
+[[ end ]]