docs/docs/reference

Knative API Reference documentation

View the latest release

The reference documentation for the latest release of the Knative is available at www.knative.dev.

Source files

The API source files are located at:

• Serving API
• Build API
• Eventing API
• Event Sources API

Updating API Reference docs (for Knative maintainers)

The Knative API reference documentation is manually generated using the gen-api-reference-docs.sh tool. If you need to generate a new version of the API docs for a recent update or for a new release, you can use the following steps.

To learn more about the tool, see the gen-crd-api-reference-docs reference page.

Before you begin

You must meet the following requirements to run the gen-api-reference-docs.sh tool:

• You need the following software installed:
  • git
  • go version 1.11+
• Clone knative/docs locally. For example: git clone git@github.com:knative/docs.git

Generating the API

To generate a version of the API:

1. Ensure that your GOPATH is empty. The gen-api-reference-docs.sh script will result in the GOPATH should not be set error if your GOPATH is configured. You view the value by running the following command:

   echo $GOPATH
   

   If your GOPATH is already configured, temporarily clear the GOPATH value by running the following command:

   export GOPATH=""
   

2. Locate the commits or tags that correspond to the version of the API that you want to generate:

   • Build
   • Eventing
   • Eventing Sources
   • Serving

3. To run the gen-api-reference-docs.sh command from the hack directory, you specify the commits or tags for each of the corresponding Knative component variables (KNATIVE_[component_name]_COMMIT):

   KNATIVE_BUILD_COMMIT=[commit_or_tag] \
   KNATIVE_EVENTING_COMMIT=[commit_or_tag] \
   KNATIVE_EVENTING_SOURCES_COMMIT=[commit_or_tag] \
   KNATIVE_SERVING_COMMIT=[commit_or_tag] \
   ./gen-api-reference-docs.sh
   

   where [commit_or_tag] is the commit or tag in the specific repo that represents the version of the API that you want to generate. Also see the example below.

   Result

   The gen-api-reference-docs.sh tool generates the API in a tmp folder. After a successful build, the tool automatically opens that folder in the tmp directory.

4. Copy the generated API files into the docs/reference directory of your knative/docs clone.

You can now perform the necessary steps to open a PR, complete a review, and merge the new API files into the appropriate branch of the knative/docs repo. See the contributor flow for details about requesting changes in the knative/docs repo.

Example

To build a set of Knative API docs for v0.3, you can use the v0.3.0 the tags from each of the Knative component repositories, like Serving v0.3.0. If you want to use a commit for Serving v0.3.0, you would use 4d198d.

Using tags from each repo, you would run the following command to generate the v0.3.0 API source files:

KNATIVE_BUILD_COMMIT=v0.3.0 \
KNATIVE_EVENTING_COMMIT=v0.3.0 \
KNATIVE_EVENTING_SOURCES_COMMIT=v0.3.0 \
KNATIVE_SERVING_COMMIT=v0.3.0 \
./gen-api-reference-docs.sh