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`.

Author: tengqm

Makefile

@@ -45,9 +45,12 @@ 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
 
+brodocsapi: cleanapi
+	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
+
 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:

gen-apidocs/generators/api/api_version.go renamed to 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)
-}