Skip to content

Commit e47dd89

Browse files
tengqmtengqm
committed
Rework API reference generator
This PR reworks the generator for API references: - Generalize the writer and reorganize packages and modules; - Add new generator for producing HTML result directly; - Fixed swagger definition that missed SchedulingClass definition. With this revised version: - We fix the problem of example code display which no longer occupy 45% of the screen; - The dependency on node JS; - The improper use of Go Template is gone; - The dependency on a docker image which team doesn't own is gone. The current "brodocs" way of reference generation is still there. We can remove it later when we are satisfied with this new "native" generator. To use the old "brodocs" generator, do `make brodocsapi` instead of `make api`.
1 parent 857109f commit e47dd89

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+7085
-1932
lines changed

‎Makefile‎

Lines changed: 61 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@ WEBROOT=~/src/github.com/kubernetes/website
22
K8SROOT=~/src/github.com/kubernetes/kubernetes
33
MINOR_VERSION=11
44

5-
APISRC=gen-apidocs/generators/build
6-
APIDST=$(WEBROOT)/docs/reference/generated/kubernetes-api/v1.$(MINOR_VERSION)
7-
APISRCFONT=$(APISRC)/node_modules/font-awesome
5+
APISRC=gen-apidocs/generators
6+
APIDST=$(WEBROOT)/static/docs/reference/generated/kubernetes-api/v1.$(MINOR_VERSION)
7+
APISRCFONT=$(APISRC)/build/node_modules/font-awesome
88
APIDSTFONT=$(APIDST)/node_modules/font-awesome
99

1010
CLISRC=gen-kubectldocs/generators/build
@@ -15,13 +15,6 @@ CLIDSTFONT=$(CLIDST)/node_modules/font-awesome
1515
default:
1616
@echo "Support commands:\ncli api comp copycli copyapi copycomp updateapispec"
1717

18-
brodocs:
19-
docker build . -t pwittrock/brodocs
20-
docker push pwittrock/brodocs
21-
22-
updateapispec:
23-
cp $(K8SROOT)/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json
24-
2518
# Build kubectl docs
2619
cleancli:
2720
sudo rm -f main
@@ -45,10 +38,6 @@ copycli: cli
4538
cp $(CLISRC)/node_modules/jquery/dist/jquery.min.js $(CLIDST)/node_modules/jquery/dist/jquery.min.js
4639
cp $(CLISRCFONT)/css/font-awesome.min.css $(CLIDSTFONT)/css/font-awesome.min.css
4740

48-
api: cleanapi
49-
go run gen-apidocs/main.go --config-dir=gen-apidocs/generators --munge-groups=false
50-
docker run -v $(shell pwd)/gen-apidocs/generators/includes:/source -v $(shell pwd)/gen-apidocs/generators/build:/build -v $(shell pwd)/gen-apidocs/generators/:/manifest pwittrock/brodocs
51-
5241
# Build kube component docs
5342
cleancomp:
5443
rm -rf $(shell pwd)/gen-compdocs/build
@@ -67,31 +56,33 @@ copycomp:
6756
cp $(shell pwd)/gen-compdocs/build/* $(WEBROOT)/docs/reference/generated/
6857

6958
# Build api docs
59+
updateapispec:
60+
cp $(K8SROOT)/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json
61+
62+
api: cleanapi
63+
go run gen-apidocs/main.go --config-dir=gen-apidocs/generators --munge-groups=false
64+
65+
# NOTE: The following "sudo" may go away when we remove docker based api doc generator
7066
cleanapi:
71-
sudo rm -f main
7267
sudo rm -rf $(shell pwd)/gen-apidocs/generators/build
7368
sudo rm -rf $(shell pwd)/gen-apidocs/generators/includes
74-
sudo rm -rf $(shell pwd)/gen-apidocs/generators/manifest.json
7569

7670
copyapi:
77-
cp $(APISRC)/index.html $(APIDST)/index.html
78-
cp $(APISRC)/navData.js $(APIDST)/navData.js
79-
cp $(APISRC)/scroll.js $(APIDST)/scroll.js
80-
cp $(APISRC)/stylesheet.css $(APIDST)/stylesheet.css
81-
cp $(APISRC)/tabvisibility.js $(APIDST)/tabvisibility.js
82-
cp $(APISRC)/node_modules/bootstrap/dist/css/bootstrap.min.css $(APIDST)/node_modules/bootstrap/dist/css/bootstrap.min.css
83-
cp $(APISRC)/node_modules/highlight.js/styles/default.css $(APIDST)/node_modules/highlight.js/styles/default.css
84-
cp $(APISRC)/node_modules/jquery.scrollto/jquery.scrollTo.min.js $(APIDST)/node_modules/jquery.scrollto/jquery.scrollTo.min.js
85-
cp $(APISRC)/node_modules/jquery/dist/jquery.min.js $(APIDST)/node_modules/jquery/dist/jquery.min.js
86-
cp $(APISRCFONT)/css/font-awesome.css $(APIDSTFONT)/css/font-awesome.css
87-
cp $(APISRCFONT)/css/font-awesome.css.map $(APIDSTFONT)/css/font-awesome.css.map
88-
cp $(APISRCFONT)/css/font-awesome.min.css $(APIDSTFONT)/css/font-awesome.min.css
89-
cp $(APISRCFONT)/fonts/FontAwesome.otf $(APIDSTFONT)/fonts/FontAwesome.otf
90-
cp $(APISRCFONT)/fonts/fontawesome-webfont.eot $(APIDSTFONT)/fonts/fontawesome-webfont.eot
91-
cp $(APISRCFONT)/fonts/fontawesome-webfont.svg $(APIDSTFONT)/fonts/fontawesome-webfont.svg
92-
cp $(APISRCFONT)/fonts/fontawesome-webfont.ttf $(APIDSTFONT)/fonts/fontawesome-webfont.ttf
93-
cp $(APISRCFONT)/fonts/fontawesome-webfont.woff $(APIDSTFONT)/fonts/fontawesome-webfont.woff
94-
cp $(APISRCFONT)/fonts/fontawesome-webfont.woff2 $(APIDSTFONT)/fonts/fontawesome-webfont.woff2
71+
cp $(APISRC)/build/index.html $(APIDST)/index.html
72+
cp $(APISRC)/build/navData.js $(APIDST)/navData.js
73+
cp $(APISRC)/static/scroll.js $(APIDST)/scroll.js
74+
mkdir -p $(APIDST)/css
75+
cp $(APISRC)/static/stylesheet.css $(APIDST)/css/stylesheet.css
76+
cp $(APISRC)/static/bootstrap.min.css $(APIDST)/css/bootstrap.min.css
77+
cp $(APISRC)/static/jquery.scrollTo.min.js $(APIDST)/jquery.scrollTo.min.js
78+
cp $(APISRC)/static/font-awesome.min.css $(APIDST)/css/font-awesome.min.css
79+
mkdir -p $(APIDST)/fonts
80+
cp $(APISRC)/static/FontAwesome.otf $(APIDST)/fonts/FontAwesome.otf
81+
cp $(APISRC)/static/fontawesome-webfont.eot $(APIDST)/fonts/fontawesome-webfont.eot
82+
cp $(APISRC)/static/fontawesome-webfont.svg $(APIDST)/fonts/fontawesome-webfont.svg
83+
cp $(APISRC)/static/fontawesome-webfont.ttf $(APIDST)/fonts/fontawesome-webfont.ttf
84+
cp $(APISRC)/static/fontawesome-webfont.woff $(APIDST)/fonts/fontawesome-webfont.woff
85+
cp $(APISRC)/static/fontawesome-webfont.woff2 $(APIDST)/fonts/fontawesome-webfont.woff2
9586

9687
# Build resource docs
9788
resource: cleanapi
@@ -104,3 +95,39 @@ copyresource: resource
10495
rm -rf gen-apidocs/generators/build/manifest.json
10596
rm -rf $(WEBROOT)/docs/resources-reference/v1.$(MINOR_VERSION)/*
10697
cp -r gen-apidocs/generators/build/* $(WEBROOT)/docs/resources-reference/v1.$(MINOR_VERSION)/
98+
99+
100+
# Brodocs way of API generation, to be removed
101+
cleanbrodocsapi:
102+
sudo rm -rf $(shell pwd)/gen-apidocs/generators/build
103+
sudo rm -rf $(shell pwd)/gen-apidocs/generators/includes
104+
sudo rm -rf $(shell pwd)/gen-apidocs/generators/manifest.json
105+
106+
brodocsapi: cleanbrodocsapi
107+
go run gen-apidocs/main.go --config-dir=gen-apidocs/generators --munge-groups=false --backend=brodocs
108+
docker run -v $(shell pwd)/gen-apidocs/generators/includes:/source -v $(shell pwd)/gen-apidocs/generators/build:/build -v $(shell pwd)/gen-apidocs/generators/:/manifest pwittrock/brodocs
109+
110+
brodocs:
111+
docker build . -t pwittrock/brodocs
112+
docker push pwittrock/brodocs
113+
114+
copybrodocsapi:
115+
cp $(APISRC)/build/index.html $(APIDST)/index.html
116+
cp $(APISRC)/build/navData.js $(APIDST)/navData.js
117+
cp $(APISRC)/build/scroll.js $(APIDST)/scroll.js
118+
cp $(APISRC)/build/stylesheet.css $(APIDST)/stylesheet.css
119+
cp $(APISRC)/build/tabvisibility.js $(APIDST)/tabvisibility.js
120+
cp $(APISRC)/build/node_modules/bootstrap/dist/css/bootstrap.min.css $(APIDST)/node_modules/bootstrap/dist/css/bootstrap.min.css
121+
cp $(APISRC)/build/node_modules/highlight.js/styles/default.css $(APIDST)/node_modules/highlight.js/styles/default.css
122+
cp $(APISRC)/build/node_modules/jquery.scrollto/jquery.scrollTo.min.js $(APIDST)/node_modules/jquery.scrollto/jquery.scrollTo.min.js
123+
cp $(APISRC)/build/node_modules/jquery/dist/jquery.min.js $(APIDST)/node_modules/jquery/dist/jquery.min.js
124+
cp $(APISRCFONT)/css/font-awesome.css $(APIDSTFONT)/css/font-awesome.css
125+
cp $(APISRCFONT)/css/font-awesome.css.map $(APIDSTFONT)/css/font-awesome.css.map
126+
cp $(APISRCFONT)/css/font-awesome.min.css $(APIDSTFONT)/css/font-awesome.min.css
127+
cp $(APISRCFONT)/fonts/FontAwesome.otf $(APIDSTFONT)/fonts/FontAwesome.otf
128+
cp $(APISRCFONT)/fonts/fontawesome-webfont.eot $(APIDSTFONT)/fonts/fontawesome-webfont.eot
129+
cp $(APISRCFONT)/fonts/fontawesome-webfont.svg $(APIDSTFONT)/fonts/fontawesome-webfont.svg
130+
cp $(APISRCFONT)/fonts/fontawesome-webfont.ttf $(APIDSTFONT)/fonts/fontawesome-webfont.ttf
131+
cp $(APISRCFONT)/fonts/fontawesome-webfont.woff $(APIDSTFONT)/fonts/fontawesome-webfont.woff
132+
cp $(APISRCFONT)/fonts/fontawesome-webfont.woff2 $(APIDSTFONT)/fonts/fontawesome-webfont.woff2
133+

‎gen-apidocs/generators/api/api_version.go‎ renamed to ‎gen-apidocs/generators/api/api.go‎

Lines changed: 27 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,35 @@ package api
1818

1919
import (
2020
"regexp"
21+
"strings"
2122
)
2223

23-
type ApiVersion string
24+
func (a ApiGroup) String() string {
25+
return string(a)
26+
}
27+
28+
func (a ApiGroups) Len() int { return len(a) }
29+
func (a ApiGroups) Swap(i, j int) { a[i], a[j] = a[j], a[i] }
30+
func (a ApiGroups) Less(i, j int) bool {
31+
// "apps" group APIs are newer than "extensions" group APIs
32+
if a[i].String() == "apps" && a[j].String() == "extensions" {
33+
return false
34+
}
35+
if a[j].String() == "apps" && a[i].String() == "extensions" {
36+
return true
37+
}
38+
return strings.Compare(a[i].String(), a[j].String()) < 0
39+
}
40+
41+
func (a ApiVersions) Len() int { return len(a) }
42+
func (a ApiVersions) Swap(i, j int) { a[i], a[j] = a[j], a[i] }
43+
func (a ApiVersions) Less(i, j int) bool {
44+
return a[i].LessThan(a[j])
45+
}
46+
47+
func (k ApiKind) String() string {
48+
return string(k)
49+
}
2450

2551
func (this ApiVersion) LessThan(that ApiVersion) bool {
2652
re := regexp.MustCompile("(v\\d+)(alpha|beta|)(\\d*)")
@@ -52,14 +78,9 @@ func (this ApiVersion) LessThan(that ApiVersion) bool {
5278
}
5379
// The string with the higher number comes first (or in the case of alpha/beta, beta comes first)
5480
if v1 != v2 {
55-
//fmt.Printf("Less than %v (%s %s) this: %s %v that: %s %v\n", v1 < v2, v1, v2, this, thisMatches, that, thatMatches)
5681
return v1 > v2
5782
}
5883
}
5984

60-
// They have the same value
6185
return false
6286
}
63-
func (a ApiVersion) String() string {
64-
return string(a)
65-
}

‎gen-apidocs/generators/api/api_group.go‎

Lines changed: 0 additions & 48 deletions
This file was deleted.

‎gen-apidocs/generators/api/api_kind.go‎

Lines changed: 0 additions & 23 deletions
This file was deleted.

0 commit comments

Comments
 (0)