Update render documentation

Render has changed in three important ways that require docs updates:

- It now uses `crossplane internal render` as its backend, the invocation of
  which can be customized.
- `crossplane render` has moved to `crossplane composition render` (though the
  old name is a hidden alias for backward compatibility).
- `crossplane alpha render op` has moved to `crossplane operation render` and,
  being an alpha command, is hidden by default.

Fixes #1084

Author: adamwg

content/master/composition/compositions.md

@@ -344,19 +344,20 @@ learn how to install and use the Crossplane CLI.
 {{< /hint >}}
 
 {{<hint "important">}}
-Running `crossplane render` requires [Docker](https://www.docker.com).
+Running `crossplane composition render` requires
+[Docker](https://www.docker.com).
 {{< /hint >}}
 
 Provide a composite resource, composition and composition functions to render
 the output locally.
 
 ```shell
-crossplane render xr.yaml composition.yaml functions.yaml
+crossplane composition render xr.yaml composition.yaml functions.yaml
 ```
 
-`crossplane render` prints resources as YAML to stdout. It prints the
-composite resource first, followed by the resources the composition functions
-created.
+`crossplane composition render` prints resources as YAML to stdout. It prints
+the composite resource first, followed by the resources the composition
+functions created.
 
 ```yaml
 ---
@@ -387,8 +388,8 @@ spec:
 
 {{<expand "The xr.yaml, composition.yaml and function.yaml files used in the example">}}
 
-You can recreate the output below by running `crossplane render` with
-these files.
+You can recreate the output below by running `crossplane composition render`
+with these files.
 
 The `xr.yaml` file contains the composite resource to render:
 
@@ -451,7 +452,8 @@ Crossplane CLI runs a function by adding an annotation in `functions.yaml`. Add
 the `render.crossplane.io/runtime` annotation to a Function to change how it's
 run.
 
-`crossplane render` supports two `render.crossplane.io/runtime` values:
+`crossplane composition render` supports two `render.crossplane.io/runtime`
+values:
 
 * `Docker` (the default) connects to Docker Engine. It uses Docker to pull and
   run a function runtime.
@@ -482,8 +484,8 @@ Use the `Development` runtime when you
 function end-to-end.
 {{</hint>}}
 
-`crossplane render` also supports the following Function annotations. These
-annotations affect how it runs Functions:
+`crossplane composition render` also supports the following Function
+annotations. These annotations affect how it runs Functions:
 
 * `render.crossplane.io/runtime-docker-cleanup` - When using the `Docker`
 runtime this annotation specifies whether the CLI should stop the function
@@ -497,6 +499,21 @@ the container, and `Orphan`, to leave it running.
   running at the specified target. It uses
   [gRPC target syntax](https://github.com/grpc/grpc/blob/v1.59.1/doc/naming.md).
 
+{{<hint "tip">}}
+The `crossplane composition render` CLI command runs the `crossplane internal
+render` command from the Crossplane controller binary. By default, it runs the
+latest stable version of Crossplane in a Docker container so that you don't need
+to download the controller binary.
+
+You can use the following flags to render using a different Crossplane version:
+
+* `--crossplane-version` to run a different Crossplane version in Docker.
+* `--crossplane-image` to select an arbitrary Crossplane Docker image (e.g.,
+  from your local mirror).
+* `--crossplane-binary` to provide an arbitrary Crossplane controller binary
+  (e.g., to test local changes to Crossplane iteslf).
+{{</hint>}}
+
 ## Verify a composition
 
 View all available Compositions with `kubectl get composition`.

content/master/guides/write-a-composition-function-in-go.md

@@ -449,8 +449,8 @@ for the SDK.
 
 ## Test the function end-to-end
 
-Test your function by adding unit tests, and by using the `crossplane render`
-command.
+Test your function by adding unit tests, and by using the `crossplane
+composition render` command.
 
 Go has rich support for unit testing. When you initialize a function from the
 template it adds some unit tests to `fn_test.go`. These tests follow Go's
@@ -617,8 +617,8 @@ Expand the following block to see example files.
 
 {{<expand "The xr.yaml, composition.yaml and function.yaml files">}}
 
-You can recreate the output below using by running `crossplane render` with
-these files.
+You can recreate the output below using by running `crossplane composition
+render` with these files.
 
 The `xr.yaml` file contains the composite resource to render:
 
@@ -677,9 +677,9 @@ spec:
 
 The Function in `functions.yaml` uses the
 {{<hover label="development" line="6">}}Development{{</hover>}}
-runtime. This tells `crossplane render` that your function is running
-locally. It connects to your locally running function instead of using Docker to
-pull and run the function.
+runtime. This tells `crossplane composition render` that your function is
+running locally. It connects to your locally running function instead of using
+Docker to pull and run the function.
 
 ```yaml {label="development"}
 apiVersion: pkg.crossplane.io/v1
@@ -702,10 +702,10 @@ to run without encryption or authentication. Only use it during testing and
 development.
 {{</hint>}}
 
-In a separate terminal, run `crossplane render`. 
+In a separate terminal, run `crossplane composition render`.
 
 ```shell
-crossplane render xr.yaml composition.yaml functions.yaml
+crossplane composition render xr.yaml composition.yaml functions.yaml
 ```
 
 This command calls your function. In the terminal where your function is running
@@ -717,8 +717,8 @@ go run . --insecure --debug
 2023-10-31T16:17:32.159-0700    INFO    function-xbuckets/fn.go:125     Added desired buckets   {"xr-version": "example.crossplane.io/v1", "xr-kind": "XBuckets", "xr-name": "example-buckets", "region": "us-east-2", "count": 3}
 ```
 
-The `crossplane render` command prints the desired resources the function
-returns.
+The `crossplane composition render` command prints the desired resources the
+function returns.
 
 ```yaml
 ---

content/master/guides/write-a-composition-function-in-python.md

@@ -335,8 +335,8 @@ for further details.
 
 ## Test the function end-to-end
 
-Test your function by adding unit tests, and by using the `crossplane render`
-command.
+Test your function by adding unit tests, and by using the `crossplane
+composition render` command.
 
 When you initialize a function from the
 template it adds some unit tests to `tests/test_fn.py`. These tests use the
@@ -479,8 +479,8 @@ Expand the following block to see example files.
 
 {{<expand "The xr.yaml, composition.yaml and function.yaml files">}}
 
-You can recreate the output below using by running `crossplane render` with
-these files.
+You can recreate the output below using by running `crossplane composition
+render` with these files.
 
 The `xr.yaml` file contains the composite resource to render:
 
@@ -537,11 +537,10 @@ spec:
 ```
 {{</expand>}}
 
-The Function in `functions.yaml` uses the
-{{<hover label="development" line="6">}}Development{{</hover>}}
-runtime. This tells `crossplane render` that your function is running
-locally. It connects to your locally running function instead of using Docker to
-pull and run the function.
+The Function in `functions.yaml` uses the {{<hover label="development"
+line="6">}}Development{{</hover>}} runtime. This tells `crossplane composition
+render` that your function is running locally. It connects to your locally
+running function instead of using Docker to pull and run the function.
 
 ```yaml {label="development"}
 apiVersion: pkg.crossplane.io/v1
@@ -563,10 +562,10 @@ hatch run development
 Only use it during testing and development.
 {{</hint>}}
 
-In a separate terminal, run `crossplane render`. 
+In a separate terminal, run `crossplane composition render`.
 
 ```shell
-crossplane render xr.yaml composition.yaml functions.yaml
+crossplane composition render xr.yaml composition.yaml functions.yaml
 ```
 
 This command calls your function. In the terminal where your function is running
@@ -578,8 +577,8 @@ hatch run development
 2024-01-11T22:12:58.153792Z [info     ] Added desired buckets          count=3 filename=fn.py lineno=68 region=us-east-2 tag=
 ```
 
-The `crossplane render` command prints the desired resources the function
-returns.
+The `crossplane composition render` command prints the desired resources the
+function returns.
 
 ```yaml
 ---

content/master/operations/operation.md

@@ -524,17 +524,22 @@ learn how to install and use the Crossplane CLI.
 {{< /hint >}}
 
 {{<hint "important">}}
-Running `crossplane alpha render op` requires [Docker](https://www.docker.com).
+`crossplane operation render` is an alpha command and is hidden by default. Run
+`crossplane config set features.enableAlpha true` to make it visible.
+{{< /hint >}}
+
+{{<hint "important">}}
+Running `crossplane operation render` requires [Docker](https://www.docker.com).
 {{< /hint >}}
 
 Provide an operation, composition functions, and any required resources to render
 the output locally.
 
 ```shell
-crossplane alpha render op operation.yaml functions.yaml --required-resources=ingress.yaml
+crossplane operation render operation.yaml functions.yaml --required-resources=ingress.yaml
 ```
 
-`crossplane alpha render op` prints the Operation status and any resources the
+`crossplane operation render` prints the Operation status and any resources the
 operation functions created or modified. It shows what would happen if you
 applied the Operation to a cluster.
 
@@ -578,17 +583,17 @@ need access to. You can specify multiple files or use glob patterns:
 
 ```shell
 # Multiple specific files
-crossplane alpha render op operation.yaml functions.yaml \
+crossplane operation render operation.yaml functions.yaml \
   --required-resources=deployment.yaml,service.yaml,configmap.yaml
 
 # Glob pattern for all YAML files in a directory
-crossplane alpha render op operation.yaml functions.yaml \
+crossplane operation render operation.yaml functions.yaml \
   --required-resources="resources/*.yaml"
 ```
 
 {{<hint "tip">}}
-Use the `crossplane alpha render op` command to test your Operations locally
-before deploying them to a cluster. The command helps validate function logic 
+Use the `crossplane operation render` command to test your Operations locally
+before deploying them to a cluster. The command helps validate function logic
 and required resource access patterns.
 {{</hint>}}