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`.
kubernetes-sigs · Jul 17, 2018 · 3922723 · 3922723
1 parent 857109f
commit 3922723
Show file tree

Hide file tree

Showing 43 changed files with 7,084 additions and 1,934 deletions.
diff --git a/Makefile b/Makefile
@@ -2,9 +2,9 @@ WEBROOT=~/src/github.com/kubernetes/website
 K8SROOT=~/src/github.com/kubernetes/kubernetes
 MINOR_VERSION=11
 
-APISRC=gen-apidocs/generators/build
-APIDST=$(WEBROOT)/docs/reference/generated/kubernetes-api/v1.$(MINOR_VERSION)
-APISRCFONT=$(APISRC)/node_modules/font-awesome
+APISRC=gen-apidocs/generators
+APIDST=$(WEBROOT)/static/docs/reference/generated/kubernetes-api/v1.$(MINOR_VERSION)
+APISRCFONT=$(APISRC)/build/node_modules/font-awesome
 APIDSTFONT=$(APIDST)/node_modules/font-awesome
 
 CLISRC=gen-kubectldocs/generators/build
@@ -15,13 +15,6 @@ CLIDSTFONT=$(CLIDST)/node_modules/font-awesome
 default:
 	@echo "Support commands:\ncli api comp copycli copyapi copycomp updateapispec"
 
-brodocs:
-	docker build . -t pwittrock/brodocs
-	docker push pwittrock/brodocs
-
-updateapispec:
-	cp $(K8SROOT)/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json
-
 # Build kubectl docs
 cleancli:
 	sudo rm -f main
@@ -45,10 +38,6 @@ copycli: cli
 	cp $(CLISRC)/node_modules/jquery/dist/jquery.min.js $(CLIDST)/node_modules/jquery/dist/jquery.min.js
 	cp $(CLISRCFONT)/css/font-awesome.min.css $(CLIDSTFONT)/css/font-awesome.min.css
 
-api: cleanapi
-	go run gen-apidocs/main.go --config-dir=gen-apidocs/generators --munge-groups=false
-	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
-
 # Build kube component docs
 cleancomp:
 	rm -rf $(shell pwd)/gen-compdocs/build
@@ -67,31 +56,30 @@ copycomp:
 	cp $(shell pwd)/gen-compdocs/build/* $(WEBROOT)/docs/reference/generated/
 
 # Build api docs
+updateapispec:
+	cp $(K8SROOT)/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json
+
+api: cleanapi
+	go run gen-apidocs/main.go --config-dir=gen-apidocs/generators --munge-groups=false
+
 cleanapi:
-	sudo rm -f main
-	sudo rm -rf $(shell pwd)/gen-apidocs/generators/build
-	sudo rm -rf $(shell pwd)/gen-apidocs/generators/includes
-	sudo rm -rf $(shell pwd)/gen-apidocs/generators/manifest.json
+	rm -rf $(shell pwd)/gen-apidocs/generators/build
+	rm -rf $(shell pwd)/gen-apidocs/generators/includes
 
 copyapi:
-	cp $(APISRC)/index.html $(APIDST)/index.html
-	cp $(APISRC)/navData.js $(APIDST)/navData.js
-	cp $(APISRC)/scroll.js $(APIDST)/scroll.js
-	cp $(APISRC)/stylesheet.css $(APIDST)/stylesheet.css
-	cp $(APISRC)/tabvisibility.js $(APIDST)/tabvisibility.js
-	cp $(APISRC)/node_modules/bootstrap/dist/css/bootstrap.min.css $(APIDST)/node_modules/bootstrap/dist/css/bootstrap.min.css
-	cp $(APISRC)/node_modules/highlight.js/styles/default.css $(APIDST)/node_modules/highlight.js/styles/default.css
-	cp $(APISRC)/node_modules/jquery.scrollto/jquery.scrollTo.min.js $(APIDST)/node_modules/jquery.scrollto/jquery.scrollTo.min.js
-	cp $(APISRC)/node_modules/jquery/dist/jquery.min.js $(APIDST)/node_modules/jquery/dist/jquery.min.js
-	cp $(APISRCFONT)/css/font-awesome.css $(APIDSTFONT)/css/font-awesome.css
-	cp $(APISRCFONT)/css/font-awesome.css.map $(APIDSTFONT)/css/font-awesome.css.map
-	cp $(APISRCFONT)/css/font-awesome.min.css $(APIDSTFONT)/css/font-awesome.min.css
-	cp $(APISRCFONT)/fonts/FontAwesome.otf $(APIDSTFONT)/fonts/FontAwesome.otf	
-	cp $(APISRCFONT)/fonts/fontawesome-webfont.eot $(APIDSTFONT)/fonts/fontawesome-webfont.eot
-	cp $(APISRCFONT)/fonts/fontawesome-webfont.svg $(APIDSTFONT)/fonts/fontawesome-webfont.svg
-	cp $(APISRCFONT)/fonts/fontawesome-webfont.ttf $(APIDSTFONT)/fonts/fontawesome-webfont.ttf
-	cp $(APISRCFONT)/fonts/fontawesome-webfont.woff $(APIDSTFONT)/fonts/fontawesome-webfont.woff
-	cp $(APISRCFONT)/fonts/fontawesome-webfont.woff2 $(APIDSTFONT)/fonts/fontawesome-webfont.woff2
+	cp $(APISRC)/build/index.html $(APIDST)/index.html
+	cp $(APISRC)/build/navData.js $(APIDST)/navData.js
+	cp $(APISRC)/static/scroll.js $(APIDST)/scroll.js
+	cp $(APISRC)/static/stylesheet.css $(APIDST)/css/stylesheet.css
+	cp $(APISRC)/static/bootstrap.min.css $(APIDST)/css/bootstrap.min.css
+	cp $(APISRC)/static/jquery.scrollTo.min.js $(APIDST)/jquery.scrollTo.min.js
+	cp $(APISRC)/static/font-awesome.min.css $(APIDST)/css/font-awesome.min.css
+	cp $(APISRC)/static/FontAwesome.otf $(APIDST)/fonts/FontAwesome.otf
+	cp $(APISRC)/static/fontawesome-webfont.eot $(APIDST)/fonts/fontawesome-webfont.eot
+	cp $(APISRC)/static/fontawesome-webfont.svg $(APIDST)/fonts/fontawesome-webfont.svg
+	cp $(APISRC)/static/fontawesome-webfont.ttf $(APIDST)/fonts/fontawesome-webfont.ttf
+	cp $(APISRC)/static/fontawesome-webfont.woff $(APIDST)/fonts/fontawesome-webfont.woff
+	cp $(APISRC)/static/fontawesome-webfont.woff2 $(APIDST)/fonts/fontawesome-webfont.woff2
 
 # Build resource docs
 resource: cleanapi
@@ -104,3 +92,39 @@ copyresource: resource
 	rm -rf gen-apidocs/generators/build/manifest.json
 	rm -rf $(WEBROOT)/docs/resources-reference/v1.$(MINOR_VERSION)/*
 	cp -r gen-apidocs/generators/build/* $(WEBROOT)/docs/resources-reference/v1.$(MINOR_VERSION)/
+
+
+# Brodocs way of API generation, to be removed
+cleanbrodocsapi:
+	sudo rm -rf $(shell pwd)/gen-apidocs/generators/build
+	sudo rm -rf $(shell pwd)/gen-apidocs/generators/includes
+	sudo rm -rf $(shell pwd)/gen-apidocs/generators/manifest.json
+
+brodocsapi: cleanbrodocsapi
+	go run gen-apidocs/main.go --config-dir=gen-apidocs/generators --munge-groups=false --backend=brodocs
+	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
+
+brodocs:
+	docker build . -t pwittrock/brodocs
+	docker push pwittrock/brodocs
+
+copybrodocsapi:
+	cp $(APISRC)/build/index.html $(APIDST)/index.html
+	cp $(APISRC)/build/navData.js $(APIDST)/navData.js
+	cp $(APISRC)/build/scroll.js $(APIDST)/scroll.js
+	cp $(APISRC)/build/stylesheet.css $(APIDST)/stylesheet.css
+	cp $(APISRC)/build/tabvisibility.js $(APIDST)/tabvisibility.js
+	cp $(APISRC)/build/node_modules/bootstrap/dist/css/bootstrap.min.css $(APIDST)/node_modules/bootstrap/dist/css/bootstrap.min.css
+	cp $(APISRC)/build/node_modules/highlight.js/styles/default.css $(APIDST)/node_modules/highlight.js/styles/default.css
+	cp $(APISRC)/build/node_modules/jquery.scrollto/jquery.scrollTo.min.js $(APIDST)/node_modules/jquery.scrollto/jquery.scrollTo.min.js
+	cp $(APISRC)/build/node_modules/jquery/dist/jquery.min.js $(APIDST)/node_modules/jquery/dist/jquery.min.js
+	cp $(APISRCFONT)/css/font-awesome.css $(APIDSTFONT)/css/font-awesome.css
+	cp $(APISRCFONT)/css/font-awesome.css.map $(APIDSTFONT)/css/font-awesome.css.map
+	cp $(APISRCFONT)/css/font-awesome.min.css $(APIDSTFONT)/css/font-awesome.min.css
+	cp $(APISRCFONT)/fonts/FontAwesome.otf $(APIDSTFONT)/fonts/FontAwesome.otf	
+	cp $(APISRCFONT)/fonts/fontawesome-webfont.eot $(APIDSTFONT)/fonts/fontawesome-webfont.eot
+	cp $(APISRCFONT)/fonts/fontawesome-webfont.svg $(APIDSTFONT)/fonts/fontawesome-webfont.svg
+	cp $(APISRCFONT)/fonts/fontawesome-webfont.ttf $(APIDSTFONT)/fonts/fontawesome-webfont.ttf
+	cp $(APISRCFONT)/fonts/fontawesome-webfont.woff $(APIDSTFONT)/fonts/fontawesome-webfont.woff
+	cp $(APISRCFONT)/fonts/fontawesome-webfont.woff2 $(APIDSTFONT)/fonts/fontawesome-webfont.woff2
+
diff --git a/gen-apidocs/generators/api/api_version.go → gen-apidocs/generators/api/api.go b/gen-apidocs/generators/api/api_version.go → gen-apidocs/generators/api/api.go
@@ -18,9 +18,35 @@ package api
 
 import (
 	"regexp"
+	"strings"
 )
 
-type ApiVersion string
+func (a ApiGroup) String() string {
+	return string(a)
+}
+
+func (a ApiGroups) Len() int      { return len(a) }
+func (a ApiGroups) Swap(i, j int) { a[i], a[j] = a[j], a[i] }
+func (a ApiGroups) Less(i, j int) bool {
+	// "apps" group APIs are newer than "extensions" group APIs
+	if a[i].String() == "apps" && a[j].String() == "extensions" {
+		return false
+	}
+	if a[j].String() == "apps" && a[i].String() == "extensions" {
+		return true
+	}
+	return strings.Compare(a[i].String(), a[j].String()) < 0
+}
+
+func (a ApiVersions) Len() int      { return len(a) }
+func (a ApiVersions) Swap(i, j int) { a[i], a[j] = a[j], a[i] }
+func (a ApiVersions) Less(i, j int) bool {
+	return a[i].LessThan(a[j])
+}
+
+func (k ApiKind) String() string {
+	return string(k)
+}
 
 func (this ApiVersion) LessThan(that ApiVersion) bool {
 	re := regexp.MustCompile("(v\\d+)(alpha|beta|)(\\d*)")
@@ -52,14 +78,9 @@ func (this ApiVersion) LessThan(that ApiVersion) bool {
 		}
 		// The string with the higher number comes first (or in the case of alpha/beta, beta comes first)
 		if v1 != v2 {
-			//fmt.Printf("Less than %v (%s %s) this: %s %v that: %s %v\n", v1 < v2, v1, v2, this, thisMatches, that, thatMatches)
 			return v1 > v2
 		}
 	}
 
-	// They have the same value
 	return false
 }
-func (a ApiVersion) String() string {
-	return string(a)
-}
diff --git a/gen-apidocs/generators/api/api_group.go b/gen-apidocs/generators/api/api_group.go
diff --git a/gen-apidocs/generators/api/api_kind.go b/gen-apidocs/generators/api/api_kind.go