Tools to build reference documentation for Kubernetes APIs and CLIs.
- Update the Makefile for your environment
- Set
K8SIOROOT
to the kubernetes/kubernetes.github.io root directory- If you have not already, clone the kubernetes/kubernetes.github.io repo
- Set
K8SROOT
to the kubernetes/kubernetes root directory- If you have not already, clone the kubernetes/kubernetes repo
- Set
MINOR_VERSION
to the kubernetes/kubernetes minor version (e.g. 8)
- Copy the
swagger.json
file from Kubernetes.
- Go to K8SROOT directory and checkout the
release-<Minor>
branch - Run
make updateapispec
to copy theswagger.json
for the kubernetes release
-
Run
make api
to build the doc html and javascript (will fail) -
Update the file
gen_open_api/config.yaml
to fix listed errors
- New APIs will be listed as "Orphaned" types, and should be added to the ToC
- New versions for existing APIs will be listed as "Orphaned" types, and should replace existing versions in the ToC
- Note: These should only appear for API types, if field types are listed as Orphaned, then there is an issue with the swagger.json compatibility
-
Run
make api
again after fixing the errors -
Create a new directory under kubernetes/kubernetes.github.io and update kubernetes/kubernetes.github.io
- From kubernetes/kubernetes.io
mkdir docs/api-reference/v1.<Minor>
- Update
docs/reference/index.md
to include the new version - Grep for references to the old version, and update them
-
Run
map copyapi
to copy the files to the kubernetes/kubernetes.github.io directory -
Update the left pannel in kubernetes/kubernetes.io
- Edit
_data/reference.yml
and add a section for the new kubectl docs
- Update the Makefile for your environment
- Set
K8SIOROOT
to the kubernetes/kubernetes.io root directory - Set
K8SROOT
to the kubernetes/kubernetes root directory - Set
MINOR_VERSION
to the kubernetes/kubernetes minor version (e.g. 8)
- Create a new directory for the kubernetes version and copy over the contents from the last release
mkdir gen-kubectldocs/generators/v1_<Minor>
cp -r gen-kubectldocs/generators/v1_<Minor-1>/* gen-kubectldocs/generators/v1_<Minor>
- Update the Kubernetes vendored src code to be for the current release
- Edit
glide.yaml
to change theversion
to release-1. - Run
glide update -v
to update the vendored code - Commit the modified files
- Build the cli docs
- Run
make cli
- Files will be copied under
gen-kubectldocs/generators/build/
- Open up
index.html
in a browser and make sure it looks good
- Fix any errors about things missing from the
gen-kubectldocs/generatorstoc.yaml
- Commands appearing in the ToC that have been removed from kubectl should be removed from the toc
- Commands appearing in kubectl but missing from the ToC should be added to a section in the
toc.yaml
-
Build the docs again after the errors have been fixed
-
Copy the cli docs to kubernetes/kubernetes.github.io
- From kubernetes/kubernetes.github.io
mkdir docs/user-guide/kubectl/v1.8
- Run
make copycli
- Files will be copied to the appropriate directory under
K8SIOROOT
- You may need to create a new directory for new kubernetes versions
- Update the left pannel in kubernetes/kubernetes.io
- Edit
_data/reference.yml
and add a section for the new kubectl docs
May need to change the image repo to one you have write access to.
-
Update Dockerfile so it will re-clone the repo
-
Run
make brodocs