Add functions section to docs (#5271)

* Add functions section to docs

* add run command

* updates from eng review

* fix headings, links

config/nav.yml

@@ -22,12 +22,17 @@ nav:
     - Tutorial:
         - Tutorial introduction: getting-started/README.md
         - Install Knative using quickstart: getting-started/quickstart-install.md
-        - Using Knative Serving:
+        - Knative Functions:
+          - About Knative Functions: getting-started/about-knative-functions.md
+          - Installing Knative Functions: getting-started/install-func.md
+          - Creating a function: getting-started/create-a-function.md
+          - Building, running, or deploying a function: getting-started/build-run-deploy-func.md
+        - Knative Serving:
           - Deploying a Knative Service: getting-started/first-service.md
           - Autoscaling: getting-started/first-autoscale.md
           - Traffic splitting: getting-started/first-traffic-split.md
-        - Using Knative Eventing:
+        - Knative Eventing:
-          - Introducing Knative Eventing: getting-started/getting-started-eventing.md
+          - About Knative Eventing: getting-started/getting-started-eventing.md
           - Sources, Brokers, and Triggers: getting-started/first-broker.md
           - Using a Knative Service as a source: getting-started/first-source.md
           - Using Triggers and sinks: getting-started/first-trigger.md
@@ -72,6 +77,14 @@ nav:
         - Upgrading with the Knative Operator: install/upgrade/upgrade-installation-with-operator.md
       # Uninstall
       - Uninstalling Knative: install/uninstall.md
+###############################################################################
+    # Functions
+###############################################################################
+    - Functions:
+      - 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
 ###############################################################################
     # Serving
 ###############################################################################

docs/client/README.md

@@ -15,11 +15,19 @@ See [Install and Set Up `kubectl`](https://kubernetes.io/docs/tasks/tools/instal
 !!! note
     `kn` cannot be used to install Knative components such as Serving or Eventing.
 
-See [Installing `kn`](install-kn.md).
+### Additional resources
 
-### kn reference documentation
+- See [Installing `kn`](install-kn.md).
+- See the [`kn` documentation]({{ clientdocs() }}){target=_blank} in Github.
 
-See the [`kn` documentation]({{ clientdocs() }}){target=_blank} in Github.
+## func
+
+The `func` CLI enables you to create, build, and deploy Knative Functions without the need to create or modify YAML files directly.
+
+### Additional resources
+
+- See [Installing Knative Functions](../functions/install-func.md).
+- See the [`func` documentation]({{ funcdocs() }}){target=_blank} in Github.
 
 ## Connecting CLI tools to your cluster
 

docs/client/kn-plugins.md

@@ -24,7 +24,7 @@ You can view all available `kn` plugins in the [Knative Sandbox repository](http
 | [kn-plugin-admin](https://github.com/knative-sandbox/kn-plugin-admin) | `kn` plugin for managing a Kubernetes based Knative installation | Y |
 | [kn-plugin-diag](https://github.com/knative-sandbox/kn-plugin-diag) | `kn` plugin for diagnosing issues by exposing detailed information for different layers of Knative objects | N |
 | [kn-plugin-event](https://github.com/knative-sandbox/kn-plugin-event) | `kn` plugin for sending events to Knative sinks | Y |
-| [kn-plugin-func](https://github.com/knative-sandbox/kn-plugin-func) | `kn` plugin for functions | Y |
+| [kn-plugin-func](https://github.com/knative/func) | `kn` plugin for functions | Y |
 | [kn-plugin-migration](https://github.com/knative-sandbox/kn-plugin-migration) | `kn` plugin for migrating Knative Services from one cluster to another | N |
 | [kn-plugin-operator](https://github.com/knative-sandbox/kn-plugin-operator) | `kn` plugin for managing Knative with Knative Operator | N |
 | [kn-plugin-quickstart](https://github.com/knative-sandbox/kn-plugin-quickstart) | `kn` plugin for developers to install a quickstart Knative cluster for experimentation purposes | Y |

docs/contributing/contributing.md

@@ -25,26 +25,26 @@ following components, look for GitHub issues marked with the good first issue la
 
 - **Knative Serving:**
 
-    - For how to get started contributing, see the [Serving development workflow](https://github.com/knative/serving/blob/main/DEVELOPMENT.md).
+    - To get started with contributing, see the [Serving development workflow](https://github.com/knative/serving/blob/main/DEVELOPMENT.md).
     - For good starter issues, see [Serving issues](https://github.com/knative/serving/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22).
 
 - **Knative Eventing:**
-    - For how to get started contributing, see the [Eventing development workflow](https://github.com/knative/eventing/blob/main/DEVELOPMENT.md).
+    - To get started with contributing, see the [Eventing development workflow](https://github.com/knative/eventing/blob/main/DEVELOPMENT.md).
     - For good starter issues, see [Eventing issues](https://github.com/knative/eventing/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Akind%2Fgood-first-issue).
 
 - **Knative Client (kn):**
 
-    - For how to get started contributing, see the [Client development workflow](https://github.com/knative/client/blob/main/docs/DEVELOPMENT.md).
+    - To get started with contributing, see the [Client development workflow](https://github.com/knative/client/blob/main/docs/DEVELOPMENT.md).
     - For good starter issues, see [Client issues](https://github.com/knative/client/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Akind%2Fgood-first-issue).
 
 - **Functions:**
 
-    - For how to get started contributing, see the [Functions development workflow](https://github.com/knative-sandbox/kn-plugin-func/blob/main/docs/CONTRIBUTING.md).
+    - To get started with contributing, see the [Functions development workflow](https://github.com/knative/func/blob/main/docs/CONTRIBUTING.md).
-    - For good starter issues, see [Functions issues](https://github.com/knative-sandbox/kn-plugin-func/issues?q=is%3Aopen+is%3Aissue+label%3Akind%2Fgood-first-issue).
+    - For good starter issues, see [Functions issues](https://github.com/knative/func/issues?q=is%3Aopen+is%3Aissue+label%3Akind%2Fgood-first-issue).
 
 - **Documentation:**
 
-    - For how to get started contributing, see the [Docs contributor guide](https://github.com/knative/docs/blob/main/contribute-to-docs/README.md#knative-docs-contributor-guide).
+    - To get started with contributing, see the [Docs contributor guide](https://github.com/knative/docs/blob/main/contribute-to-docs/README.md#knative-docs-contributor-guide).
     - For good starter issues, see [Documentation issues](https://github.com/knative/docs/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Akind%2Fgood-first-issue).
 
 ## Contribute code samples to the community

docs/functions/README.md

@@ -0,0 +1,16 @@
+# Knative Functions overview
+
+--8<-- "about-functions.md"
+
+## Function templates
+
+--8<-- "functions-templates-intro.md"
+
+## Language packs
+
+Functions can be written in any language supported by the available [language packs](https://github.com/knative/func/blob/main/docs/language-pack-providers/language-pack-contract.md){target=_blank}.
+<!--TODO: Remove and replace with lang pack snippet in future PR, similar to templates-->
+
+## Getting started with functions
+
+Before you can use Knative Functions, you must have access to a Knative development environment. To set up a development environment, you can follow the [Knative Quickstart tutorial](../getting-started/){target=_blank}.

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

@@ -0,0 +1,41 @@
+# 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/creating-functions.md

@@ -0,0 +1,3 @@
+# Creating functions
+
+--8<-- "create-a-function.md"

docs/functions/install-func.md

@@ -0,0 +1,11 @@
+# Installing Knative Functions
+
+--8<-- "install-functions-intro.md"
+
+## Installing the `func` CLI
+
+--8<-- "install-func-CLI.md"
+
+## Installing the `kn func` CLI plugin
+
+--8<-- "install-kn-func-plugin.md"

docs/getting-started/about-knative-functions.md

@@ -0,0 +1,3 @@
+# About Knative Functions
+
+--8<-- "about-functions.md"

docs/getting-started/build-run-deploy-func.md

@@ -0,0 +1,41 @@
+# 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/getting-started/create-a-function.md

@@ -0,0 +1,5 @@
+# Creating a function
+
+--8<-- "create-a-function.md"
+
+<!--TODO: Add details about languages / templates in a follow up PR-->

docs/getting-started/getting-started-eventing.md

@@ -1,4 +1,4 @@
-# Introducing Knative Eventing
+# About Knative Eventing
 
 Knative Eventing provides you with helpful tools that can be used to create event-driven applications, by easily attaching event sources, triggers, and other options to your Knative Services.
 

docs/getting-started/install-func.md

@@ -0,0 +1,11 @@
+# Installing Knative Functions
+
+--8<-- "install-functions-intro.md"
+
+## Installing the `func` CLI
+
+--8<-- "install-func-CLI.md"
+
+## Installing the `kn func` CLI plugin
+
+--8<-- "install-kn-func-plugin.md"

docs/snippets/about-functions.md

@@ -0,0 +1,10 @@
+<!-- Snippet used in the following topics:
+- /docs/functions/README.md
+-->
+Knative Functions provides a simple programming model for using functions on Knative, without requiring in-depth knowledge of Knative, Kubernetes, containers, or dockerfiles.
+
+Knative Functions enables you to easily create, build, and deploy stateless, event-driven functions as Knative Services by using the `func` CLI.
+
+When you build or run a function, an [Open Container Initiative (OCI) format](https://opencontainers.org/about/overview/){target=_blank} container image is generated automatically for you, and is stored in a container registry. Each time you update your code and then run or deploy it, the container image is also updated.
+
+You can create functions and manage function workflows by using the `func` CLI, or by using the `kn func` plugin for the Knative CLI.

docs/snippets/build-func-intro.md

@@ -0,0 +1,5 @@
+<!-- Snippet used in the following topics:
+- /docs/getting-started/build-run-deploy-func.md
+- /docs/functions/build-run-deploy-func.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

@@ -0,0 +1,22 @@
+<!-- Snippet used in the following topics:
+- /docs/concepts/eventing-resources/brokers.md
+-->
+After you have installed Knative Functions, you can create a function project by using the `func` CLI or the `kn func` plugin:
+
+=== "`func` CLI"
+
+    ```bash
+    func create -l go hello
+    ```
+
+=== "`kn func` plugin"
+
+    ```bash
+    kn func create -l go hello
+    ```
+
+!!! Success "Expected output"
+
+    ```{ .bash .no-copy }
+    Created go function in hello
+    ```

docs/snippets/deploy-func-intro.md

@@ -0,0 +1,4 @@
+<!-- Snippet used in the following topics:
+- /docs/getting-started/build-run-deploy-func.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/functions-templates-intro.md

@@ -0,0 +1,13 @@
+<!-- Snippet used in the following topics:
+- /docs/functions/README.md
+-->
+Knative Functions provides templates that can be used to create basic functions, by initiating a function project boilerplate when you run a `create` command.
+
+Templates allow you to choose the language and invocation format for your function. The following templates are available with both CloudEvent and HTTP invocation formats:
+
+- [Node.js](https://github.com/knative/func/blob/main/docs/function-developers/nodejs.md){target=_blank}
+- [Python](https://github.com/knative/func/blob/main/docs/function-developers/python.md){target=_blank}
+- [Go](https://github.com/knative/func/blob/main/docs/function-developers/golang.md){target=_blank}
+- [Quarkus](https://github.com/knative/func/blob/main/docs/function-developers/quarkus.md){target=_blank}
+- [Rust](https://github.com/knative/func/blob/main/docs/function-developers/rust.md){target=_blank}
+- [TypeScript](https://github.com/knative/func/blob/main/docs/function-developers/typescript.md){target=_blank}

docs/snippets/install-func-CLI.md

@@ -0,0 +1,91 @@
+<!-- Snippet used in the following topics:
+- /docs/functions/install-func.md
+- /docs/getting-started/install-func.md
+-->
+=== "Homebrew"
+
+    To install `func` using Homebrew, run the following commands:
+
+    ```bash
+    brew tap knative-sandbox/kn-plugins
+    ```
+
+    ```bash
+    brew install func
+    ```
+
+    If you have already installed the `kn` CLI by using Homebrew, the `func` CLI is automatically recognized as a plugin to `kn`, and can be referenced as `kn func` or `func` interchangeably.
+
+    !!! note
+        Use `brew upgrade` instead if you are upgrading from a previous version.
+
+=== "Executable binary"
+
+    You can install `func` by downloading the executable binary for your system and placing it in the system path.
+
+    1. Download the binary for your system from the [`func` release page](https://github.com/knative/func/releases){target=_blank}.
+
+    1. Rename the binary to `func` and make it executable by running the following commands:
+
+        ```bash
+        mv <path-to-binary-file> func
+        ```
+
+        ```bash
+        chmod +x func
+        ```
+
+        Where `<path-to-binary-file>` is the path to the binary file you downloaded in the previous step, for example, `func_darwin_amd64` or `func_linux_amd64`.
+
+    1. Move the executable binary file to a directory on your PATH by running the command:
+
+        ```bash
+        mv func /usr/local/bin
+        ```
+
+    1. Verify that the CLI is working by running the command:
+
+        ```bash
+        func version
+        ```
+
+=== "Go"
+
+    1. Check out the `func` client repository and navigate to the `func` directory:
+
+        ```bash
+        git clone https://github.com/knative/func.git func
+        ```
+
+        ```bash
+        cd func/
+        ```
+
+    1. Build an executable binary:
+
+        ```bash
+        make
+        ```
+
+    1. Move `func` into your system path, and verify that `func` commands are working properly. For example:
+
+        ```bash
+        func version
+        ```
+
+=== "Container image"
+
+    Run `func` from a container image. For example:
+
+    ```bash
+    docker run --rm -it ghcr.io/knative/func/func create -l node -t http myfunc
+    ```
+
+    Links to images are available here:
+
+    - [Latest release](https://gcr.io/knative-releases/knative.dev/client/cmd/kn){target=_blank}
+
+    !!! note
+        Running `func` from a container image does not place the binary on a permanent path. This procedure must be repeated each time you want to use `func`.
+
+<!--TODO: Maybe needs an update when https://github.com/knative/func/issues/1308 is fixed-->

docs/snippets/install-functions-intro.md

@@ -0,0 +1,4 @@
+<!-- Snippet used in the following topics:
+- /docs/functions/install-func.md
+-->
+You can install Knative Functions either by using the standalone `func` CLI, or by installing the `kn func` plugin that is available for the Knative `kn` CLI.

docs/snippets/install-kn-func-plugin.md

@@ -0,0 +1,33 @@
+<!-- Snippet used in the following topics:
+- /docs/functions/install-func.md
+- /docs/getting-started/install-func.md
+-->
+=== "kn plugin"
+
+    You can install Knative Functions as a `kn` CLI plugin, by downloading the executable binary for your system and placing it in the system path.
+
+    1. Download the binary for your system from the [`func` release page](https://github.com/knative/func/releases){target=_blank}.
+
+    1. Rename the binary to `kn-func`, and make it executable by running the following commands:
+
+        ```bash
+        mv <path-to-binary-file> kn-func
+        ```
+
+        ```bash
+        chmod +x kn-func
+        ```
+
+        Where `<path-to-binary-file>` is the path to the binary file you downloaded in the previous step, for example, `func_darwin_amd64` or `func_linux_amd64`.
+
+    1. Move the executable binary file to a directory on your PATH by running the command:
+
+        ```bash
+        mv kn-func /usr/local/bin
+        ```
+
+    1. Verify that the CLI is working by running the command:
+
+        ```bash
+        kn func version
+        ```

docs/snippets/proc-building-function.md

@@ -0,0 +1,21 @@
+<!-- Snippet used in the following topics:
+- /docs/getting-started/build-run-deploy-func.md
+- /docs/functions/build-run-deploy-func.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.
+
+=== "func"
+
+    To build the function, run the following command:
+
+    ```bash
+    func build
+    ```
+
+=== "kn func"
+
+    To build the function, run the following command:
+
+    ```bash
+    kn func build
+    ```

docs/snippets/proc-deploying-function.md

@@ -0,0 +1,58 @@
+<!-- Snippet used in the following topics:
+- /docs/getting-started/build-run-deploy-func.md
+- /docs/functions/build-run-deploy-func.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.
+
+=== "func"
+
+    Deploy the function by running the command inside the project directory:
+
+    ```bash
+    func deploy --registry <registry>
+    ```
+
+=== "kn func"
+
+    Deploy the function by running the command inside the project directory:
+
+    ```bash
+    kn func deploy --registry <registry>
+    ```
+
+!!! Success "Expected output"
+    ```{ .bash .no-copy }
+        🙌 Function image built: <registry>/hello:latest
+        ✅ Function deployed in namespace "default" and exposed at URL:
+        http://hello.default.127.0.0.1.sslip.io
+    ```
+
+You can verify that your function has been successfully deployed by using the `invoke` command and observing the output:
+
+=== "func"
+
+    ```bash
+    func invoke
+    ```
+
+=== "kn func"
+
+    ```bash
+    kn func invoke
+    ```
+
+!!! Success "Expected output"
+    ```{ .bash .no-copy }
+    Received response
+    POST / HTTP/1.1 hello.default.127.0.0.1.sslip.io
+      User-Agent: Go-http-client/1.1
+      Content-Length: 25
+      Accept-Encoding: gzip
+      Content-Type: application/json
+      K-Proxy-Request: activator
+      X-Request-Id: 9e351834-0542-4f32-9928-3a5d6aece30c
+      Forwarded: for=10.244.0.15;proto=http
+      X-Forwarded-For: 10.244.0.15, 10.244.0.9
+      X-Forwarded-Proto: http
+    Body:
+    ```

docs/snippets/proc-running-function.md

@@ -0,0 +1,79 @@
+<!-- Snippet used in the following topics:
+- /docs/getting-started/build-run-deploy-func.md
+- /docs/functions/build-run-deploy-func.md
+-->
+The `run` command builds an image for your function if required, and runs this image locally, instead of deploying it on a cluster.
+
+=== "func"
+
+    Run the function locally, by running the command inside the project directory:
+
+    ```bash
+    func run
+    ```
+
+    Using this command also builds the function if necessary.
+
+    You can force a rebuild of the image by running the command:
+
+    ```bash
+    func run --build
+    ```
+
+    It is also possible to disable the build, by running the command:
+
+    ```bash
+    func run --build=false
+    ```
+
+=== "kn func"
+
+    Run the function locally, by running the command inside the project directory:
+
+    ```bash
+    kn func run
+    ```
+
+    Using this command also builds the function if necessary.
+
+    You can force a rebuild of the image by running the command:
+
+    ```bash
+    kn func run --build
+    ```
+
+    It is also possible to disable the build, by running the command:
+
+    ```bash
+    kn func run --build=false
+    ```
+
+You can verify that your function has been successfully run by using the `invoke` command and observing the output:
+
+=== "func"
+
+    ```bash
+    func invoke
+    ```
+
+=== "kn func"
+
+    ```bash
+    kn func invoke
+    ```
+
+!!! Success "Expected output"
+    ```{ .bash .no-copy }
+    Received response
+    POST / HTTP/1.1 hello.default.127.0.0.1.sslip.io
+      User-Agent: Go-http-client/1.1
+      Content-Length: 25
+      Accept-Encoding: gzip
+      Content-Type: application/json
+      K-Proxy-Request: activator
+      X-Request-Id: 9e351834-0542-4f32-9928-3a5d6aece30c
+      Forwarded: for=10.244.0.15;proto=http
+      X-Forwarded-For: 10.244.0.15, 10.244.0.9
+      X-Forwarded-Proto: http
+    Body:
+    ```

docs/snippets/run-func-intro.md

@@ -0,0 +1,5 @@
+<!-- Snippet used in the following topics:
+- /docs/getting-started/build-run-deploy-func.md
+- /docs/functions/build-run-deploy-func.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.

hack/macros.py

@@ -131,8 +131,6 @@ def define_env(env):
             print_to_stdout(f'exception raised for {org}/{repo}/{file}\n', traceback.format_exc())
             sys.exit(1)
 
-
-
     @env.macro
     def clientdocs():
         """Generates a link to the client docs for the current release version.
@@ -145,3 +143,15 @@ def define_env(env):
         if version is None:
             return 'https://github.com/knative/client/blob/main/docs/cmd/kn.md'
         return 'https://github.com/knative/client/blob/{version}/docs/cmd/kn.md'.format(version=version)
+
+    @env.macro
+    def funcdocs():
+        """Generates a link to the func docs for the current release version.
+        When the version in the SAMPLES_BRANCH environment variable is
+        empty this links to the main branch, otherwise it links to the
+        matching release in Github.
+        """
+        version = os.environ.get("SAMPLES_BRANCH")
+        if version is None:
+            return 'https://github.com/knative/func/blob/main/docs/reference/func.md'
+        return 'https://github.com/knative/func/blob/{version}/docs/reference/func.md'.format(version=version)