We use analytics and cookies to understand site traffic. Information about your use of our site is shared with Google for that purpose. Learn more.
Building API docs from the Knative component repos
New API docs are generated and then published at https://www.knative.dev/docs/reference/api for every release.
API source files are located at:
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
- You need the following software installed:
- Clone knative/docs locally. For example:
git clone email@example.com:knative/docs.git
Generating the API
To generate a version of the API:
Ensure that your
GOPATHis empty. The
gen-api-reference-docs.shscript will result in the
GOPATH should not be seterror if your
GOPATHis configured. You view the value by running the following command:
GOPATHis already configured, temporarily clear the
GOPATHvalue by running the following command:
Locate the commits or tags that correspond to the version of the API that you want to generate:
To run the
gen-api-reference-docs.shcommand from the
hackdirectory, you specify the commits or tags for each of the corresponding Knative component variables (
cd hack KNATIVE_SERVING_COMMIT=[commit_or_tag] \ KNATIVE_EVENTING_COMMIT=[commit_or_tag] \ ./gen-api-reference-docs.sh
[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.
gen-api-reference-docs.shtool generates the API in a
tmpfolder. After a successful build, the tool automatically opens that folder in the
If the script fails, there are a couple possible causes.
If you get the
F1116 15:21:23.549503 63473 main.go:129] no API packages found in ./pkg/apiserror, check if a new version of the script is available: https://github.com/ahmetb/gen-crd-api-reference-docs/tags
The script is kept up-to-date with changes that go into the Kubernetes API. As Knative adds support for those APIs, you might need to make sure the corresponding script
gen-crd-api-reference-docsversion is used.
If you get the
F0807 13:58:20.621526 168834 main.go:444] type invalid type has kind=Unsupported which is unhandlederror, the import target might have moved. There might be other causes for that error but view #2054 (and the linked Issues) for details about how we handled that error in the past.
Copy the generated API files into the
docs/referencedirectory of your knative/docs clone.
The linter now fails for content with trailing whitespaces. Use a tool of your choice to remove all trailing whitespace. For example, search for and remove:
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
See the contributor flow for details
about requesting changes in the
To build a set of Knative API docs for v0.18, you can use the
v0.18.0 the tags
from each of the Knative component repositories, like
Serving v0.18.0. If you want to
use a commit for Serving v0.18.0, you would use
Using tags from each repo, you would run the following command to generate the v0.18.0 API source files:
KNATIVE_SERVING_COMMIT=v0.18.0 \ KNATIVE_EVENTING_COMMIT=v0.18.0 \ ./gen-api-reference-docs.sh
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.