Skip to content

Commit 4939d6d

Browse files
aimeeuaimeeu
committed
add pages
Signed-off-by: Aimee Ukasick <[email protected]>
1 parent 6fac5df commit 4939d6d

File tree

3 files changed

+246
-0
lines changed

3 files changed

+246
-0
lines changed

‎img/reference-yml-for-script.png

137 KB
Loading

‎k8s-ref-docs/manual-gen-api-and-kubectl.md

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
# Manually generate API and kubectl reference docs
2+
3+
## Prerequisites
4+
5+
1. Golang version that is [supported](https://github.com/kubernetes/community/blob/master/contributors/devel/development.md#go) by Kubernetes; currently Golan v1.12.x
6+
2. Git
7+
3. Hugo 57.2 OR Docker for building and testing the website locally
8+
4. Your kubernetes/website fork is up to date with upstream/master
9+
10+
## Create Go workspace and set GOPATH
11+
This presumes you start in your HOME directory.
12+
```bash
13+
mkdir ref-docs-gen
14+
cd ref*
15+
mkdir src
16+
export GOPATH=$HOME/ref-docs-gen/src
17+
echo $GOPATH
18+
```
19+
20+
21+
22+
## Generate API reference docs
23+
24+
### Clone repos
25+
Make sure your website fork is up-to-date with upstream/master. Clone the release branch of `kubernetes/kubernetes`.
26+
27+
```bash
28+
go get -u github.com/go-openapi/loads
29+
go get -u github.com/go-openapi/spec
30+
go get -u github.com/kubernetes-sigs/reference-docs
31+
git clone [email protected]:aimeeu/website.git $GOPATH/src/github.com/aimeeu/website
32+
git clone --single-branch --branch release-1.17 https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes
33+
```
34+
35+
![Filesystem](../img/apiGenLocalRepos.png)
36+
37+
### Update kubernetes-sigs/reference-docs makefile
38+
Update WEBROOT, K8SROOT, AND MINOR_VERSION.
39+
40+
```yaml
41+
WEBROOT=~/ref-docs-gen/src/github.com/aimeeu/website
42+
K8SROOT=~/ref-docs-gen/src/github.com/k8s.io/kubernetes
43+
MINOR_VERSION=17
44+
```
45+
46+
### Make the docs
47+
48+
Change to the kubernetes-sigs/reference-docs directory. Run ```make updateapispec```.
49+
50+
Output is
51+
```
52+
cp ~/ref-docs-gen/src/k8s.io/kubernetes/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json
53+
```
54+
55+
Run ```make api```.
56+
57+
The first few lines of out are similar to:
58+
```
59+
sudo rm -rf /home/aimee/ref-docs-gen/src/github.com/kubernetes-sigs/reference-docs/gen-apidocs/generators/build
60+
[sudo] password for aimee:
61+
sudo rm -rf /home/aimee/ref-docs-gen/src/github.com/kubernetes-sigs/reference-docs/gen-apidocs/generators/includes
62+
go run gen-apidocs/main.go --config-dir=gen-apidocs/generators --munge-groups=false
63+
Current Version: apiextensions.v1.CustomResourceDefinitionCondition Old Versions: [apiextensions.v1beta1.CustomResourceDefinitionCondition,]
64+
Current Version: rbac.v1.RoleRef Old Versions: [rbac.v1beta1.RoleRef,rbac.v1alpha1.RoleRef,]
65+
```
66+
67+
Verify nav files have been created by running:
68+
69+
```
70+
[ -e "gen-apidocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
71+
```
72+
73+
and
74+
75+
```
76+
[ -e "gen-apidocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"
77+
```
78+
79+
Create a v1.<MINOR_VERSION> directory in website/static/docs/reference/generated/kubernetes-api
80+
81+
Copy files to website directory by running ```make copyapi```.
82+
83+
### Manually update the minor version in the API reference index page
84+
85+
Change to the website directory.
86+
87+
File: ```website/content/en/docs/reference/kubernetes-api/api-index.md```
88+
89+
```
90+
---
91+
title: v1.17
92+
---
93+
94+
[Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/)
95+
```
96+
97+
### Manually add link to new version of API Docs
98+
99+
File: ```website/content/en/docs/reference/_index.md```
100+
101+
Add a new line in the ```## API Reference``` section. Remove the oldest version.
102+
103+
```
104+
* [Kubernetes API Overview](/docs/reference/using-api/api-overview/) - Overview of the API for Kubernetes.
105+
* Kubernetes API Versions
106+
* [1.17](/docs/reference/generated/kubernetes-api/v1.17/)
107+
* [1.16](/docs/reference/generated/kubernetes-api/v1.16/)
108+
* [1.15](/docs/reference/generated/kubernetes-api/v1.15/)
109+
* [1.14](/docs/reference/generated/kubernetes-api/v1.14/)
110+
* [1.13](/docs/reference/generated/kubernetes-api/v1.13/)
111+
```
112+
113+
### View new and updated files
114+
115+
Run ```git status``` to see the new and updated files. Output is similar to:
116+
117+
```
118+
Changes not staged for commit:
119+
(use "git add <file>..." to update what will be committed)
120+
(use "git checkout -- <file>..." to discard changes in working directory)
121+
122+
modified: content/en/docs/reference/_index.md
123+
modified: content/en/docs/reference/kubernetes-api/api-index.md
124+
125+
Untracked files:
126+
(use "git add <file>..." to include in what will be committed)
127+
128+
static/docs/reference/generated/kubernetes-api/v1.17/
129+
130+
no changes added to commit (use "git add" and/or "git commit -a")
131+
```
132+
## Genereate kubectl reference docs
133+
134+
### Clone repos
135+
Change to ```$HOME/ref-docs-gen/src```.
136+
137+
```
138+
go get -u github.com/spf13/pflag
139+
go get -u github.com/spf13/cobra
140+
go get -u gopkg.in/yaml.v2
141+
```
142+
143+
### Remove the spf13 package from k8s.io/kubernetes
144+
145+
```
146+
rm -rf k8s.io/kubernetes/vendor/github.com/spf13
147+
```
148+
149+
### Create <MINOR_VERSION> directory
150+
151+
Change to the ```kubernetes-sigs/reference-docs/gen-kubectldocs/generators```
152+
directory. Create a new ```<MINOR_VERSION>``` directory based on the most recent
153+
minor version.
154+
155+
```
156+
mkdir gen-kubectldocs/generators/v1_17
157+
cp -r gen-kubectldocs/generators/v1_16/* gen-kubectldocs/generators/v1_16
158+
```
159+
160+
### Make the docs
161+
162+
Change to ```kubernetes-sigs/reference-docs```.
163+
164+
Run ```make copycli```.
165+
166+
The first several lines of output are similar to:
167+
168+
```
169+
sudo rm -f main
170+
[sudo] password for aimee:
171+
sudo rm -rf /home/aimee/ref-docs-gen/src/github.com/kubernetes-sigs/reference-docs/gen-kubectldocs/generators/includes
172+
sudo rm -rf /home/aimee/ref-docs-gen/src/github.com/kubernetes-sigs/reference-docs/gen-kubectldocs/generators/build
173+
sudo rm -rf /home/aimee/ref-docs-gen/src/github.com/kubernetes-sigs/reference-docs/gen-kubectldocs/generators/manifest.json
174+
go run gen-kubectldocs/main.go --kubernetes-version v1_17
175+
docker run -v /home/aimee/ref-docs-gen/src/github.com/kubernetes-sigs/reference-docs/gen-kubectldocs/generators/includes:/source -v /home/aimee/ref-docs-gen/src/github.com/kubernetes-sigs/reference-docs/gen-kubectldocs/generators/build:/build -v /home/aimee/ref-docs-gen/src/github.com/kubernetes-sigs/reference-docs/gen-kubectldocs/generators/:/manifest pwittrock/brodocs
176+
Unable to find image 'pwittrock/brodocs:latest' locally
177+
latest: Pulling from pwittrock/brodocs
178+
386a066cd84a: Pull complete
179+
75ea84187083: Pull complete
180+
88b459c9f665: Pull complete
181+
```
182+
183+
Verify nav files have been created by running:
184+
185+
```
186+
[ -e "gen-kubectldocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
187+
```
188+
189+
and
190+
191+
```
192+
[ -e "gen-kubectldocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"
193+
```
194+
195+
Change to the website directory. Run ```git status``` to see the new and updated files. Output is similar to:
196+
197+
```
198+
Changes to be committed:
199+
(use "git reset HEAD <file>..." to unstage)
200+
201+
modified: content/en/docs/reference/_index.md
202+
modified: content/en/docs/reference/kubernetes-api/index.md
203+
new file: static/docs/reference/generated/kubernetes-api/v1.17/
204+
205+
Changes not staged for commit:
206+
(use "git add <file>..." to update what will be committed)
207+
(use "git checkout -- <file>..." to discard changes in working directory)
208+
209+
modified: static/docs/reference/generated/kubectl/kubectl-commands.html
210+
modified: static/docs/reference/generated/kubectl/navData.js
211+
modified: static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
212+
```
213+
214+
## Test website locally if desired
215+
216+
Run ```hugo server```.

‎k8s-ref-docs/script-gen-api-and-kubectl.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Use update-imported-docs.py to generate API and kubectl reference docs
2+
3+
## Prerequisites
4+
5+
1. Golang version that is [supported](https://github.com/kubernetes/community/blob/master/contributors/devel/development.md#go) by Kubernetes (currently Golan v1.12.x); the Golang binary must be in your PATH
6+
2. Git
7+
3. Python 3.x (creation of a virtual environment recommended)
8+
4. Hugo 57.2 OR Docker for building and testing the website locally
9+
5. Your `kubernetes/website` fork is up to date with upstream/master
10+
11+
## Clone the website repo
12+
13+
```
14+
git clone [email protected]:aimeeu/website.git
15+
```
16+
17+
## Update the reference.yml file
18+
19+
Change to the `website/update-imported-docs` directory.
20+
21+
1. Either change `git checkout release-1.16` to the release you want (e.g. 1.17) OR replace those three lines with:
22+
23+
```
24+
git clone --single-branch --branch release-1.17 https://github.com/kubernetes/kubernetes.git src/k8s.io/kubernetes
25+
cd src/k8s.io/Kubernetes
26+
```
27+
2. The `update-imported-docs.py` script does not create the directories for style sheets and other static content; nor does it copy that content from the `kubernetes-sigs/reference-docs` directory. Solve this by adding `make copyapi` and `make copycli` after `make comp`.
28+
29+
30+
![reference.yml](../img/reference-yml-for-script.png)

0 commit comments

Comments
 (0)