[release-1.7] Follow up to add advanced func docs (#5304)

* Follow up to add advanced func docs

* fix heading

Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>

config/nav.yml

@@ -84,7 +84,11 @@ nav:
       - Knative Functions overview: functions/README.md
       - Installing Knative Functions: functions/install-func.md
       - Creating functions: functions/creating-functions.md
-      - Building, running, or deploying functions: functions/build-run-deploy-func.md
+      - Building functions: functions/building-functions.md
+      - Running functions: functions/running-functions.md
+      - Deploying functions: functions/deploying-functions.md
+      - Invoking functions: functions/invoking-functions.md
+      - Language packs: functions/language-packs.md
 ###############################################################################
     # Serving
 ###############################################################################

docs/functions/build-run-deploy-func.md

@@ -1,41 +0,0 @@
-# Building, running, or deploying functions
-
-After you have created a function project, you can build, run, or deploy your function, depending on your use case.
-
-## Running a function
-
---8<-- "run-func-intro.md"
-
-### Prerequisites
-
-- You have a Docker daemon on your local machine. This is already provided if you have used the Quickstart installation.
-
-### Procedure
-
---8<-- "proc-running-function.md"
-
-## Deploying a function
-
---8<-- "deploy-func-intro.md"
-
-### Prerequisites
-
-- You have a Docker daemon on your local machine. This is already provided if you have used the Quickstart installation.
-
-- You have access to a container registry and are able to push images to this registry.
-
-### Procedure
-
---8<-- "proc-deploying-function.md"
-
-## Building a function
-
---8<-- "build-func-intro.md"
-
-### Prerequisites
-
-- You have a Docker daemon on your local machine. This is already provided if you have used the Quickstart installation.
-
-### Procedure
-
---8<-- "proc-building-function.md"

docs/functions/building-functions.md

@@ -0,0 +1,42 @@
+# Building functions
+
+--8<-- "build-func-intro.md"
+
+## Local builds
+
+You can build a container image for your function locally without deploying it to a cluster, by using the `build` command.
+
+### Prerequisites
+
+- You have a Docker daemon on your local machine. This is already provided if you have used the Quickstart installation.
+
+### Procedure
+
+--8<-- "proc-building-function.md"
+
+## On-cluster Builds
+
+If you do not have a local Docker daemon running, or you are using a CI/CD pipeline, you might want to build your function on the cluster instead of using a local build. You can create an on-cluster build by using the `func deploy --remote` command.
+
+### Prerequisites
+
+- The function must exist in a Git repository.
+- You must configure your cluster to use Tekton Pipelines. See the [on-cluster build](https://github.com/knative/func/blob/main/docs/reference/on_cluster_build.md){target=_blank} documentation.
+
+### Procedure
+
+When running the command for the first time, you must specify the Git URL for the function:
+
+=== "func"
+
+    ```{ .console }
+    func deploy --remote --registry <registry> --git-url <git-url> -p hello
+    ```
+
+=== "kn func"
+
+    ```{ .console }
+    kn func deploy --remote --registry <registry> --git-url <git-url> -p hello
+    ```
+
+After you have specified the Git URL for your function once, you can omit it in subsequent commands.

docs/functions/deploying-functions.md

@@ -0,0 +1,13 @@
+# Deploying functions
+
+--8<-- "deploy-func-intro.md"
+
+## Prerequisites
+
+- You have a Docker daemon on your local machine. This is already provided if you have used the Quickstart installation.
+
+- You have access to a container registry and are able to push images to this registry.
+
+## Procedure
+
+--8<-- "proc-deploying-function.md"

docs/functions/invoking-functions.md

@@ -0,0 +1,10 @@
+# Invoking functions
+
+You can use the `func invoke` command to send a test request to invoke a
+function either locally or on your Knative cluster.
+
+This command can be used to test that a function is working and able to receive HTTP requests and CloudEvents correctly.
+
+If your function is running locally, `func invoke` sends a test request to the local instance.
+
+You can use the `func invoke` command to send test data to your function with the `--data` flag, as well as other options to simulate different types of requests. See the [func invoke](https://github.com/knative/func/blob/main/docs/reference/func_invoke.md){target=_blank} documentation for more information.

docs/functions/language-packs.md

@@ -0,0 +1,32 @@
+# Language packs
+
+Language packs can be used to extend Knative Functions to support additional runtimes, function signatures, operating systems, and installed tooling for functions. Language Packs are distributed through Git repositories or as a directory on a disc.
+
+For more information see the [language pack](https://github.com/knative/func/blob/main/docs/language-pack-providers/language-pack-contract.md){target=_blank} documentation.
+
+## Using external Git repositories
+
+When creating a new function, a Git repository can be specified as the source
+for the template files. The Knative Sandbox maintains a set of [example templates](https://github.com/knative-sandbox/func-tastic){target=_blank} which can be used during project creation.
+
+For example, you can run the following command to use the [`metacontroller`](https://metacontroller.github.io/metacontroller/){target=_blank} template for Node.js:
+
+```{ .console }
+func create myfunc -l nodejs -t metacontroller --repository https://github.com/knative-sandbox/func-tastic
+```
+
+## Installing language packs locally
+
+Language packs can be installed locally by using the [`func repository`](https://github.com/knative/func/blob/main/docs/reference/func_repository.md){target=_blank} command.
+
+For example, to add the Knative Sandbox example templates, you can run the following command:
+
+```{ .console }
+func repository add knative https://github.com/knative-sandbox/func-tastic
+```
+
+After the Knative Sandbox example templates are installed, you can use the `metacontroller` template by specifying the `knative` prefix in the `create` command:
+
+```{ .console }
+func create -t knative/metacontroller -l nodejs my-controller-function
+```

docs/functions/running-functions.md

@@ -0,0 +1,11 @@
+# Running functions
+
+--8<-- "run-func-intro.md"
+
+## Prerequisites
+
+- You have a Docker daemon on your local machine. This is already provided if you have used the Quickstart installation.
+
+## Procedure
+
+--8<-- "proc-running-function.md"

docs/snippets/build-func-intro.md

@@ -1,5 +1,5 @@
 <!-- Snippet used in the following topics:
 - /docs/getting-started/build-run-deploy-func.md
-- /docs/functions/build-run-deploy-func.md
+- /docs/functions/building-functions.md
 -->
 Building a function creates an OCI container image for your function that can be pushed to a container registry. It does not run or deploy the function, which can be useful if you want to build a container image for your function locally, but do not want to automatically run the function or deploy it to a cluster, for example, in a testing scenario.

docs/snippets/create-a-function.md

@@ -5,12 +5,24 @@ After you have installed Knative Functions, you can create a function project by
 
 === "`func` CLI"
 
+    ```bash
+    func create -l <language> <function-name>
+    ```
+
+    Example:
+
     ```bash
     func create -l go hello
     ```
 
 === "`kn func` plugin"
 
+    ```bash
+    kn func create -l <language> <function-name>
+    ```
+
+    Example:
+
     ```bash
     kn func create -l go hello
     ```
@@ -20,3 +32,5 @@ After you have installed Knative Functions, you can create a function project by
     ```{ .bash .no-copy }
     Created go function in hello
     ```
+
+For more information about options for function `create` commands, see the [func create](https://github.com/knative/func/blob/main/docs/reference/func_create.md){target=_blank} documentation.

docs/snippets/deploy-func-intro.md

@@ -1,4 +1,5 @@
 <!-- Snippet used in the following topics:
 - /docs/getting-started/build-run-deploy-func.md
+- /docs/functions/deploying-functions.md
 -->
 Deploying a function creates an OCI container image for your function, and pushes this container image to your image registry. The function is deployed to the cluster as a Knative Service. Redeploying a function updates the container image and resulting Service that is running on your cluster. Functions that have been deployed to a cluster are accessible on the cluster just like any other Knative Service.

docs/snippets/proc-building-function.md

@@ -1,6 +1,6 @@
 <!-- Snippet used in the following topics:
 - /docs/getting-started/build-run-deploy-func.md
-- /docs/functions/build-run-deploy-func.md
+- /docs/functions/building-functions.md
 -->
 The `build` command uses the project name and the image registry name to construct a fully qualified container image name for the function. If the function project has not previously been built, you are prompted to provide an image registry.
 

docs/snippets/proc-deploying-function.md

@@ -1,6 +1,6 @@
 <!-- Snippet used in the following topics:
 - /docs/getting-started/build-run-deploy-func.md
-- /docs/functions/build-run-deploy-func.md
+- /docs/functions/deploying-functions.md
 -->
 The `deploy` command uses the function project name as the Knative Service name. When the function is built, the project name and the image registry name are used to construct a fully qualified image name for the function.
 

docs/snippets/proc-running-function.md

@@ -1,6 +1,6 @@
 <!-- Snippet used in the following topics:
 - /docs/getting-started/build-run-deploy-func.md
-- /docs/functions/build-run-deploy-func.md
+- /docs/functions/running-functions.md
 -->
 The `run` command builds an image for your function if required, and runs this image locally, instead of deploying it on a cluster.
 

docs/snippets/run-func-intro.md

@@ -1,5 +1,5 @@
 <!-- Snippet used in the following topics:
 - /docs/getting-started/build-run-deploy-func.md
-- /docs/functions/build-run-deploy-func.md
+- /docs/functions/running-functions.md
 -->
 Running a function creates an OCI container image for your function before running the function in your local environment, but does not deploy the function to a cluster. This can be useful if you want to run your function locally for a testing scenario.