Improve generation of reference docs

.github/workflows/ci.yml

@@ -176,3 +176,38 @@ jobs:
           AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_PSW }}
           AWS_DEFAULT_REGION: us-east-1
         run: nix run --option warn-dirty false .#promote-artifacts -- main "$VERSION" master
+
+  # Validate our generated docs.
+  validate-docs:
+    permissions:
+      contents: read
+    runs-on: ubuntu-24.04
+    needs: [build-artifacts]
+
+    steps:
+      - name: Checkout crossplane/docs
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          repository: crossplane/docs
+          persist-credentials: false
+          path: ./docs
+
+      - name: Download Artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: output
+          path: .
+
+      - name: Generate docs
+        run: |
+          chmod +x ./bin/linux_amd64/crossplane
+          ./bin/linux_amd64/crossplane generate-docs -o ./docs/content/master/cli/command-reference.md
+
+      - name: Install Vale
+        env:
+          VALE_VERSION: "3.14.2"
+        run: wget https://github.com/errata-ai/vale/releases/download/v${{env.VALE_VERSION}}/vale_${{env.VALE_VERSION}}_Linux_64-bit.tar.gz && tar -xvzf vale_${{env.VALE_VERSION}}_Linux_64-bit.tar.gz
+
+      - name: Run Vale
+        run: |
+          ./vale --config="./docs/utils/vale/.vale.ini" ./docs/content/master/cli/command-reference.md | tee /dev/stderr | wc -l | { read wc; test $wc -eq 1; }

cmd/crossplane/composition/generate.go

@@ -53,12 +53,12 @@ const (
 )
 
 type generateCmd struct {
-	XRD         string `arg:""                                              help:"Path to the CompositeResourceDefinition (XRD) file."`
-	Name        string `help:"Name prefix for the composition."             optional:""`
-	Plural      string `help:"Custom plural for the CompositeTypeRef.Kind." optional:""`
-	Path        string `help:"Output file path override."                   optional:""`
-	ProjectFile string `default:"crossplane-project.yaml"                   help:"Path to project definition file."                    short:"f"`
-	CacheDir    string `env:"CROSSPLANE_XPKG_CACHE"                         help:"Directory for cached xpkg package contents."         name:"cache-dir"`
+	XRD         string `arg:""                                        help:"Path to the CompositeResourceDefinition (XRD) file."`
+	Name        string `help:"Name prefix for the composition."       optional:""`
+	Plural      string `help:"Custom plural for the referenced kind." optional:""`
+	Path        string `help:"Output file."                           optional:""`
+	ProjectFile string `default:"crossplane-project.yaml"             help:"Path to project definition file."                    short:"f"`
+	CacheDir    string `env:"CROSSPLANE_XPKG_CACHE"                   help:"Directory for cached xpkg package contents."         name:"cache-dir"`
 
 	projFS     afero.Fs
 	apisFS     afero.Fs

cmd/crossplane/composition/help/generate.md

@@ -1,5 +1,5 @@
 The `composition generate` command creates a Composition for a
-CompositeResourceDefinition (XRD). The Composition is scaffolded with a single
+CompositeResourceDefinition (XRD). The generated Composition contains a single
 pipeline step that runs `function-auto-ready`, which is automatically added to
 the project's dependencies if it isn't already present.
 
@@ -19,13 +19,13 @@ crossplane composition generate examples/network/network-aws.yaml --name aws
 ```
 
 Generate a Composition with a custom plural form, useful when automatic
-pluralization is wrong (e.g., "postgres"):
+pluralization is wrong (for example, "postgres"):
 
 ```shell
 crossplane composition generate examples/database/database.yaml --plural postgreses
 ```
 
-Write the generated Composition to a specific path within the project:
+Write the generated Composition to a specific path:
 
 ```shell
 crossplane composition generate apis/network/definition.yaml --path apis/network/composition.yaml

cmd/crossplane/config/config.go

@@ -30,8 +30,8 @@ type ConfigPath string //nolint:revive // The "Config" stutter is intentional; t
 // Cmd groups subcommands for inspecting and modifying the CLI config file.
 type Cmd struct {
 	// Keep subcommands sorted alphabetically.
-	Set  setCmd  `cmd:"" help:"Set a config value and write it to the config file."`
-	View viewCmd `cmd:"" help:"Print the current effective config as YAML."`
+	Set  setCmd  `cmd:"" help:"Set a value and write it to the configuration file." novale:"gitlab.SubstitutionWarning[\"config\"]"`
+	View viewCmd `cmd:"" help:"Print the current effective configuration as YAML."  novale:"gitlab.SubstitutionWarning[\"config\"]"`
 }
 
 // Help returns the extended help for the config command.

cmd/crossplane/config/help/config.md

@@ -1,13 +1,13 @@
 The `config` command manages the configuration file for the `crossplane`
-CLI. The config file location is, in priority order:
+CLI. The configuration 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:
+Show the current effective configuration:
 
 ```shell
 crossplane config view

cmd/crossplane/config/set.go

@@ -29,7 +29,7 @@ import (
 )
 
 type setCmd struct {
-	Key   string `arg:"" help:"Config key to set (e.g. features.enableAlpha)."`
+	Key   string `arg:"" help:"Key to set (for example, features.enableAlpha)."`
 	Value string `arg:"" help:"Value to assign."`
 
 	fs afero.Fs

cmd/crossplane/convert/compositionenvironment/cmd.go

@@ -41,12 +41,12 @@ var helpDetail string
 // Cmd arguments and flags for converting a Composition to use function-environment-configs.
 type Cmd struct {
 	// Arguments.
-	InputFile string `arg:"" default:"-" help:"The Composition file to be converted. If not specified or '-', stdin will be used." optional:"" predictor:"file" type:"path"`
+	InputFile string `arg:"" default:"-" help:"The Composition file to convert or '-' for stdin." optional:"" predictor:"file" type:"path"`
 
 	// Flags.
-	OutputFile string `help:"The file to write the generated Composition to. If not specified, stdout will be used." placeholder:"PATH" predictor:"file" short:"o" type:"path"`
+	OutputFile string `help:"The file to write the generated Composition to; omit for stdout." placeholder:"PATH" predictor:"file" short:"o" type:"path"`
 
-	FunctionEnvironmentConfigRef string `default:"function-environment-configs" help:"Name of the existing function-environment-configs Function, to be used to reference it." name:"function-environment-configs-ref"`
+	FunctionEnvironmentConfigRef string `default:"function-environment-configs" help:"Name of the installed function-environment-configs Function." name:"function-environment-configs-ref"`
 
 	fs afero.Fs
 }

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

@@ -1,11 +1,11 @@
 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.
+Environments (removed in Crossplane 1.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`.
+function name is `function-environment-configs`, but this can be overridden with
+`--function-environment-configs-ref`.
 
 ## Examples
 

cmd/crossplane/convert/help/convert.md

@@ -1,6 +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:
+The supported conversions are:
 
 - Native Composition Environment → `function-environment-configs`

cmd/crossplane/dependency/add.go

@@ -41,14 +41,14 @@ var addHelp string
 
 // addCmd adds a dependency to the current project.
 type addCmd struct {
-	Package     string `arg:""                            help:"Package to be added (e.g. xpkg.crossplane.io/crossplane-contrib/provider-nop:v0.5.0, k8s:v1.33.0, a git repo URL, or an HTTP URL)."`
-	ProjectFile string `default:"crossplane-project.yaml" help:"Path to project definition file."                                                                                                   short:"f"`
-	CacheDir    string `env:"CROSSPLANE_XPKG_CACHE"       help:"Directory for cached xpkg package contents."                                                                                        name:"cache-dir"`
+	Package     string `arg:""                            help:"Package to add (xpkg OCI reference, k8s:<version>, git repository URL, or HTTP(S) URL)."`
+	ProjectFile string `default:"crossplane-project.yaml" help:"Path to project definition file."                                                        short:"f"`
+	CacheDir    string `env:"CROSSPLANE_XPKG_CACHE"       help:"Directory for cached xpkg package contents."                                             name:"cache-dir"`
 
 	// Flags for specific dependency types.
 	APIOnly bool   `help:"Mark an xpkg dependency as API-only (not a runtime dependency)." name:"api-only"`
 	GitRef  string `help:"Git ref for CRD dependencies (branch, tag, or commit SHA)."      name:"git-ref"`
-	GitPath string `help:"Path within the git repository for CRD dependencies."            name:"git-path"`
+	GitPath string `help:"Path to CRDs in the git repository."                             name:"git-path"`
 }
 
 func (c *addCmd) Help() string {

cmd/crossplane/dependency/dependency.go

@@ -19,7 +19,7 @@ package dependency
 
 // Cmd contains commands for dependency management.
 type Cmd struct {
-	Add         addCmd         `cmd:"" help:"Add a dependency to the current project."`
+	Add         addCmd         `cmd:"" help:"Add a dependency to the current project."             novale:"Google.WordList[\"k8s\"],Google.Units,gitlab.Units"`
 	UpdateCache updateCacheCmd `cmd:"" help:"Update the dependency cache for the current project."`
 	CleanCache  cleanCacheCmd  `cmd:"" help:"Clean the dependency cache."`
 }

cmd/crossplane/dependency/help/add.md

@@ -1,6 +1,6 @@
-The `dependency add` command adds a dependency to a Crossplane Project. The
-dependency is added to the project's metadata file and language bindings
-(schemas) are generated its CRDs when applicable.
+The `dependency add` command adds a dependency to a Crossplane Project metadata
+file and generates language bindings (schemas) for the dependency package's
+CRDs.
 
 ## Dependency types
 
@@ -13,10 +13,9 @@ Projects support three kinds of dependencies:
 An xpkg dependency may be either a runtime dependency (the default) or a
 build-time dependency. Runtime dependencies become dependencies of the
 Configuration produced by `crossplane project build` or `crossplane project run`
-and thus get installed into a cluster when the Configuration is
-installed. Build-time dependencies, on the other hand, are used only for schema
-generation and do not become Configuration dependencies. Use the `--api-only`
-flag to indicate that an xpkg dependency should be build-time only.
+and are thus installed into a cluster with the Configuration. Build-time
+dependencies have schemas generated but don't become Configuration
+dependencies. Use the `--api-only` flag to add a build-time xpkg dependency.
 
 Non-xpkg dependencies are always build-time dependencies.
 

cmd/crossplane/dependency/help/update-cache.md

@@ -1,6 +1,4 @@
 The `dependency update-cache` command updates the local dependency cache for the
-current project. It caches all dependencies listed in the
-`crossplane-project.yaml` file and re-generates language bindings (schemas) for
-them if needed. Any dependency whose version is expressed as a semantic version
-constraint will have the constraint re-resolved to a specific version (i.e.,
-schemas will be updated if a newer version is available).
+current project. It re-resolves semantic version constraints to specific
+versions (fetching newer versions if available), caches all dependencies, and
+re-generates language bindings (schemas) for them if needed.

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

@@ -6,9 +6,17 @@ description: "Command reference for the Crossplane CLI"
 
 <!-- This file is generated by `crossplane generate-docs`. Do not edit by hand. -->
 
+<!-- We have a special spelling checker for the CLI docs that allows lower-case
+"crossplane", since it's the name of the command and we use it everywhere. -->
+<!-- vale Crossplane.Spelling = NO -->
+<!-- vale cli-docs = YES -->
+
 This documentation is for the `crossplane` CLI [[ .Version ]].
 
 [[ range .Commands ]]
+[[- range .NoVale ]]
+<!-- vale [[ . ]] = NO -->
+[[- end ]]
 <!-- vale Google.Headings = NO -->
 <!-- vale Microsoft.Headings = NO -->
 [[ .Heading ]] [[ .FullPath ]]
@@ -42,4 +50,10 @@ crossplane [[ .Summary ]]
 [[ range .Flags ]]| [[ if .Short ]]`[[ .Short ]]`[[ end ]] | `[[ .Long ]]` | [[ if .Required ]]**Required.** [[ end ]][[ .Help ]] |
 [[ end ]]{{< /table >}}
 [[ end ]]
+[[- range .NoVale ]]
+<!-- vale [[ . ]] = YES -->
+[[- end ]]
 [[ end ]]
+
+<!-- vale cli-docs = NO -->
+<!-- vale Crossplane.Spelling = YES -->

cmd/crossplane/docs.go

@@ -78,6 +78,7 @@ type docsCommand struct {
 	Summary    string
 	Positional []docsPositional
 	Flags      []docsFlag
+	NoVale     []string
 }
 
 // docsInput is the top-level template input.
@@ -126,6 +127,11 @@ func buildDocsCommand(n *kong.Node) docsCommand {
 		Detail:     normalizeDetail(n.Detail, headingLevel),
 		Summary:    n.Summary(),
 	}
+
+	if n.Tag != nil && n.Tag.Get("novale") != "" {
+		dc.NoVale = strings.Split(n.Tag.Get("novale"), ",")
+	}
+
 	for _, p := range n.Positional {
 		dc.Positional = append(dc.Positional, docsPositional{
 			Display:  p.Summary(),
@@ -200,6 +206,13 @@ func normalizeDetail(detail string, headingLevel int) string {
 		bqRE := regexp.MustCompile(`^> \*\*(\w+):\*\* `)
 		bqMatch := bqRE.FindStringSubmatch(line)
 		if bqMatch != nil {
+			// Omit the feature enablement message from the top-level command
+			// detail, since it's not useful in the generated docs. It's a
+			// little gross that we're hard-coding this, but it's good enough.
+			if strings.Contains(line, "Alpha and beta features are enabled.") {
+				continue
+			}
+
 			bq = true
 			fmt.Fprintf(&sb, "{{<hint \"%s\" >}}\n", strings.ToLower(bqMatch[1]))
 			line = strings.TrimPrefix(line, bqMatch[0])
@@ -227,6 +240,14 @@ func normalizeDetail(detail string, headingLevel int) string {
 		sb.WriteString(line + "\n")
 	}
 
+	// Close the "hint" box if it appeared at the very end of the detail.
+	if bq {
+		sb.WriteString("{{< /hint >}}\n")
+	}
+	if table {
+		sb.WriteString("{{< /table >}}\n")
+	}
+
 	return strings.TrimSpace(sb.String())
 }
 

cmd/crossplane/function/help/generate.md

@@ -1,7 +1,7 @@
 The `function generate` command creates an embedded function in the specified
-language under the project's `functions/` directory. If a path to a Composition
-file is supplied, the new function is also idempotently added as a step to the
-end of the Composition's pipeline.
+language under the project's `functions/` directory. It optionally idempotently
+adds the new function to the end of a Composition's pipeline when given a
+Composition path.
 
 ## Supported languages
 

cmd/crossplane/main.go

@@ -75,7 +75,7 @@ type cli struct {
 	// Subcommands.
 	Cluster     cluster.Cmd     `cmd:"" help:"Inspect a Crossplane cluster."                                            maturity:"beta"`
 	Composition composition.Cmd `cmd:"" help:"Work with Crossplane Compositions."`
-	Config      configcmd.Cmd   `cmd:"" help:"View and modify the crossplane CLI config file."`
+	Config      configcmd.Cmd   `cmd:"" help:"View and update the crossplane CLI configuration file."                   novale:"gitlab.SubstitutionWarning[\"config\"]"`
 	Dependency  dependency.Cmd  `cmd:"" help:"Manage dependencies of control plane Projects."                           maturity:"beta"`
 	Function    function.Cmd    `cmd:"" help:"Work with functions in control plane Projects."                           maturity:"beta"`
 	Operation   operation.Cmd   `cmd:"" help:"Work with Crossplane Operations."                                         maturity:"alpha"`
@@ -92,7 +92,7 @@ type cli struct {
 	GenerateDocs docsCmd `cmd:"" help:"Generate command-reference docs in markdown format." hidden:""`
 
 	// Flags.
-	ConfigPath string      `env:"CROSSPLANE_CONFIG"                  help:"Path to the crossplane CLI config file." name:"config" placeholder:"PATH"`
+	ConfigPath string      `env:"CROSSPLANE_CONFIG"                  help:"Path to the crossplane CLI configuration file." name:"config" placeholder:"PATH"`
 	Verbose    verboseFlag `help:"Print verbose logging statements." name:"verbose"`
 
 	// Completion

cmd/crossplane/project/help/build.md

@@ -1,16 +1,17 @@
-The `project build` command builds a Crossplane Project into a set of xpkgs.  It
+The `project build` command builds a Crossplane Project into a set of xpkgs. It
 builds each embedded function in the project and a Configuration package that
-ties everything together. A special `.xpkg` file containing all the built
-packages is written to the project's output directory (`_output/` by
-default). This file can be consumed by the `project push` command to push the
-packages to an OCI registry.
-
-The repository for the built Configuration is taken from `spec.repository` in
-`crossplane-project.yaml`. Override it for a single build with `--repository`.
-
-> **Important:** The repository is used to construct the function names used for
-> embedded function references in compositions. The same repository must be
-> specified when building and pushing a project.
+ties everything together. The output of the build is a special `.xpkg` file
+containing all the built packages, placed in the project's output directory
+(`_output/` by default). The `project push` command can consume packages from
+the output file and push them to an OCI registry.
+
+The `build` command constructs the repository for the built Configuration from
+`spec.repository` in `crossplane-project.yaml`. Override it for a single build
+with `--repository`.
+
+> **Important:** The repository influences the function names used for embedded
+> function references in compositions. You must specify the same repository when
+> building and pushing a project.
 
 The build reuses the dependency cache populated by `crossplane dependency add`
 and `crossplane dependency update-cache`. Override the cache location with

cmd/crossplane/project/help/init.md

@@ -3,8 +3,8 @@ creates a target directory containing a minimal `crossplane-project.yaml` along
 with the standard sub-directories used by the DevEx tooling: `apis`,
 `functions`, `examples`, `tests`, and `operations`.
 
-The project name must be a valid DNS-1035 label. By default the project is
-created in a new directory named after the project; use `--directory` (`-d`) to
+The project name must be a valid DNS-1035 label. By default, the `init` command
+creates a new directory named after the project; use `--directory` (`-d`) to
 choose a different target directory.
 
 ## Examples

cmd/crossplane/project/help/push.md

@@ -1,17 +1,17 @@
 The `project push` command pushes the xpkgs produced by `crossplane project
 build` to an OCI registry. It pushes both the Configuration package and any
-embedded function packages built from the project. Credentials for the registry
-are taken from the local `docker` configuration; pushing to a private registry
-may require a prior `docker login`.
+embedded function packages built from the project. The `push` command uses
+registry credentials from the local `docker` configuration; pushing to a private
+registry may require a prior `docker login`.
 
 By default the command pushes to the repository specified in
 `crossplane-project.yaml` and uses a tag generated from the package contents.
 Override either with `--repository` and `--tag` (`-t`). To push a specific
 package file instead of the project's default output, use `--package-file`.
 
-> **Important:** The repository is used to construct the function names used for
-> embedded function references in compositions. The same repository must be
-> specified when building and pushing a project.
+> **Important:** The repository influences the function names used for embedded
+> function references in compositions. You must specify the same repository when
+> building and pushing a project.
 
 ## Examples