Merge pull request #172 from tengqm/add-api-group-list

Add support for generating API group version list

gen-apidocs/generators/api/definition.go

@@ -31,11 +31,11 @@ import (
 // inlineDefinition is a definition that should be inlined when displaying a Concept
 // instead of appearing the in "Definitions"
 type inlineDefinition struct {
-	Name string
+	Name  string
 	Match string
 }
 
-var _INLINE_DEFINITIONS = []inlineDefinition {
+var _INLINE_DEFINITIONS = []inlineDefinition{
 	{Name: "Spec", Match: "${resource}Spec"},
 	{Name: "Status", Match: "${resource}Status"},
 	{Name: "List", Match: "${resource}List"},
@@ -47,8 +47,9 @@ var _INLINE_DEFINITIONS = []inlineDefinition {
 
 func NewDefinitions(specs []*loads.Document) Definitions {
 	s := Definitions{
-		All:	map[string]*Definition{},
-		ByKind: map[string]SortDefinitionsByVersion{},
+		All:           map[string]*Definition{},
+		ByKind:        map[string]SortDefinitionsByVersion{},
+		GroupVersions: map[string]ApiVersions{},
 	}
 
 	LoadDefinitions(specs, &s)
@@ -115,7 +116,7 @@ func (s *Definitions) initialize() {
 		}
 	}
 
-	// Initialize Inline, IsInlined 
+	// Initialize Inline, IsInlined
 	// Note: examples of inline definitions are "Spec", "Status", "List", etc
 	for _, d := range s.All {
 		for _, name := range s.getInlineDefinitionNames(d.Name) {
@@ -278,7 +279,7 @@ func (d *Definition) GetResourceName() string {
 }
 
 func (d *Definition) initExample(config *Config) {
-	path := filepath.Join(ConfigDir, config.ExampleLocation, d.Name, d.Name + ".yaml")
+	path := filepath.Join(ConfigDir, config.ExampleLocation, d.Name, d.Name+".yaml")
 	file := strings.Replace(strings.ToLower(path), " ", "_", -1)
 	content, err := ioutil.ReadFile(file)
 	if err != nil || len(content) <= 0 {

gen-apidocs/generators/api/open_api.go

@@ -102,7 +102,8 @@ func buildGroupMap(specs []*loads.Document) map[string]string {
 }
 
 func LoadDefinitions(specs []*loads.Document, s *Definitions) {
-	groups := map[string]string{}
+	var versionList ApiVersions
+
 	groupMapping := buildGroupMap(specs)
 	for _, spec := range specs {
 		for name, spec := range spec.Spec().Definitions {
@@ -111,7 +112,7 @@ func LoadDefinitions(specs []*loads.Document, s *Definitions) {
 				resource = r
 			}
 
-			// This actually skips the following groupsi, i.e. old definitions
+			// This actually skips the following groups, i.e. old definitions
 			//  'io.k8s.kubernetes.pkg.api.*'
 			//  'io.k8s.kubernetes.pkg.apis.*'
 			if strings.HasPrefix(spec.Description, "Deprecated. Please use") {
@@ -129,7 +130,6 @@ func LoadDefinitions(specs []*loads.Document, s *Definitions) {
 			} else if group == "error" {
 				panic(errors.New(fmt.Sprintf("Could not locate group for %s", name)))
 			}
-			groups[group] = ""
 
 			full_group, found := groupMapping[group]
 			if !found {
@@ -149,6 +149,28 @@ func LoadDefinitions(specs []*loads.Document, s *Definitions) {
 			}
 
 			s.All[d.Key()] = d
+
+			// skip "io.k8s.apimachinery.pkg.api.resource.*"
+			// skip "meta" group also
+			if version == "resource" || group == "meta" {
+				continue
+			}
+
+			versionList, found = s.GroupVersions[full_group]
+			if !found {
+				s.GroupVersions[full_group] = ApiVersions{ApiVersion(version)}
+			} else {
+				found = false
+				for _, v := range versionList {
+					if v.String() == version {
+						found = true
+					}
+				}
+				if !found {
+					versionList = append(versionList, ApiVersion(version))
+					s.GroupVersions[full_group] = versionList
+				}
+			}
 		}
 	}
 }

gen-apidocs/generators/api/types.go

@@ -66,6 +66,7 @@ func (a ApiGroups) Less(i, j int) bool {
 }
 
 type ApiKind string
+
 func (k ApiKind) String() string {
 	return string(k)
 }
@@ -189,10 +190,15 @@ type Definition struct {
 	Resource string
 }
 
+type GroupVersions map[string]ApiVersions
+
 // Definitions indexes open-api definitions
 type Definitions struct {
 	All    map[string]*Definition
 	ByKind map[string]SortDefinitionsByVersion
+
+	// Available API groups and their versions
+	GroupVersions GroupVersions
 }
 
 type DefinitionList []*Definition

gen-apidocs/generators/html.go

@@ -79,6 +79,49 @@ func (h *HTMLWriter) WriteOverview() {
 	h.CurrentSection = &item
 }
 
+func (h *HTMLWriter) WriteAPIGroupVersions(gvs api.GroupVersions) {
+	fn := "_group_versions.html"
+	path := filepath.Join(api.IncludesDir, fn)
+	f, err := os.Create(path)
+	defer f.Close()
+	if err != nil {
+		os.Stderr.WriteString(fmt.Sprintf("%v", err))
+		os.Exit(1)
+	}
+
+	fmt.Fprintf(f, h.DefaultStaticContent("API Groups"))
+	fmt.Fprintf(f, "<P>The API Groups and their versions are summarized in the following table.</P>")
+	fmt.Fprintf(f, "<TABLE class=\"col-md-8\">\n<THEAD><TR><TH>Group</TH><TH>Version</TH></TR></THEAD>\n<TBODY>\n")
+
+	groups := api.ApiGroups{}
+	for group, _ := range gvs {
+		groups = append(groups, api.ApiGroup(group))
+	}
+	sort.Sort(groups)
+
+	for _, group := range groups {
+		versionList, _ := gvs[group.String()]
+		sort.Sort(versionList)
+		var versions []string
+		for _, v := range versionList {
+			versions = append(versions, v.String())
+		}
+
+		fmt.Fprintf(f, "<TR><TD><CODE>%s</CODE></TD><TD><CODE>%s</CODE></TD></TR>\n",
+			group, strings.Join(versions, ", "))
+	}
+	fmt.Fprintf(f, "</TBODY>\n</TABLE>\n")
+
+	item := TOCItem{
+		Level: 1,
+		Title: "API Groups",
+		Link:  "-strong-api-groups-strong-",
+		File:  fn,
+	}
+	h.TOC.Sections = append(h.TOC.Sections, &item)
+	h.CurrentSection = &item
+}
+
 func (h *HTMLWriter) WriteResourceCategory(name, file string) {
 	writeStaticFile(name, "_"+file+".html", h.DefaultStaticContent(name))
 	link := strings.Replace(strings.ToLower(name), " ", "-", -1)

gen-apidocs/generators/writer.go

@@ -34,6 +34,7 @@ type DocWriter interface {
 	Extension() string
 	DefaultStaticContent(title string) string
 	WriteOverview()
+	WriteAPIGroupVersions(gvs api.GroupVersions)
 	WriteResourceCategory(name, file string)
 	WriteResource(r *api.Resource)
 	WriteDefinitionsOverview()
@@ -61,6 +62,9 @@ func GenerateFiles() {
 	writer := NewHTMLWriter(config, copyright, title)
 	writer.WriteOverview()
 
+	// Write API groups
+	writer.WriteAPIGroupVersions(config.Definitions.GroupVersions)
+
 	// Write resource definitions
 	for _, c := range config.ResourceCategories {
 		writer.WriteResourceCategory(c.Name, c.Include)