Skip to content

Commit

Permalink
Rework API reference generator
Browse files Browse the repository at this point in the history 
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`.
  • Loading branch information
@tengqm
tengqm committed Jul 17, 2018
1 parent 857109f commit e47dd89
Show file tree
Hide file tree
Showing 43 changed files with 7,085 additions and 1,932 deletions.
95 changes: 61 additions & 34 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -67,31 +56,33 @@ 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

# NOTE: The following "sudo" may go away when we remove docker based api doc generator
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

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
mkdir -p $(APIDST)/css
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
mkdir -p $(APIDST)/fonts
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
Expand All @@ -104,3 +95,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

33 changes: 27 additions & 6 deletions gen-apidocs/generators/api/api_version.go → gen-apidocs/generators/api/api.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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*)")
Expand Down Expand Up @@ -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)
}
48 changes: 0 additions & 48 deletions gen-apidocs/generators/api/api_group.go
View file

This file was deleted.

23 changes: 0 additions & 23 deletions gen-apidocs/generators/api/api_kind.go
View file

This file was deleted.

Loading

0 comments on commit e47dd89

Please sign in to comment.