Don't use apiserver-builder to generate reference documentation.

Author: pwittrock

build/apiserverbuilder/Dockerfile

@@ -85,7 +85,7 @@ ENV GOOS darwin
 ENV GOARCH amd64
 ENV DEST /usr/local/kubebuilder/bin/
 RUN mkdir -p $DEST || echo ""
-RUN git clone https://github.com/kubernetes-incubator/reference-docs $GOPATH/src/github.com/kubernetes-incubator/reference-docs --depth=1
+RUN git clone https://github.com/kubernetes-incubator/reference-docs $GOPATH/src/github.com/kubernetes-incubator/reference-docs --branch kubebuilder  --depth=1
 RUN go build -o $DEST/gen-apidocs github.com/kubernetes-incubator/reference-docs/gen-apidocs
 
 # Copy all binaries into a single tar.gz file

build/apiserverbuilder/docs.sh

@@ -68,7 +68,7 @@ ENV GOOS linux
 ENV GOARCH amd64
 ENV DEST /usr/local/kubebuilder/bin/
 RUN mkdir -p $DEST || echo ""
-RUN git clone https://github.com/kubernetes-incubator/reference-docs $GOPATH/src/github.com/kubernetes-incubator/reference-docs --depth=1
+RUN git clone https://github.com/kubernetes-incubator/reference-docs $GOPATH/src/github.com/kubernetes-incubator/reference-docs --branch kubebuilder --depth=1
 RUN go build -o $DEST/gen-apidocs github.com/kubernetes-incubator/reference-docs/gen-apidocs
 
 FROM golang:1.10-stretch as linux

build/thirdparty/darwin/Dockerfile

@@ -24,6 +24,7 @@ import (
 	"path/filepath"
 	"strings"
 
+	generatecmd "github.com/kubernetes-sigs/kubebuilder/cmd/kubebuilder/generate"
 	"github.com/kubernetes-sigs/kubebuilder/cmd/kubebuilder/util"
 	"github.com/spf13/cobra"
 )
@@ -59,12 +60,16 @@ kubebuilder docs
 var generateConfig bool
 var cleanup, verbose bool
 var outputDir string
+var copyright string
 
 func AddDocs(cmd *cobra.Command) {
 	docsCmd.Flags().BoolVar(&cleanup, "cleanup", true, "If true, cleanup intermediary files")
 	docsCmd.Flags().BoolVar(&verbose, "verbose", true, "If true, use verbose output")
 	docsCmd.Flags().BoolVar(&generateConfig, "generate-config", true, "If true, generate the docs/reference/config.yaml.")
 	docsCmd.Flags().StringVar(&outputDir, "output-dir", filepath.Join("docs", "reference"), "Build docs into this directory")
+	docsCmd.Flags().StringVar(&copyright, "copyright", filepath.Join("hack", "boilerplate.go.txt"), "Location of copyright boilerplate file.")
+	docsCmd.Flags().StringVar(&generatecmd.Docscopyright, "docs-copyright", "<a href=\"https://github.com/kubernetes/kubernetes\">Copyright 2018 The Kubernetes Authors.</a>", "html for the copyright text on the docs")
+	docsCmd.Flags().StringVar(&generatecmd.Docstitle, "title", "API Reference", "title of the docs page")
 	cmd.AddCommand(docsCmd)
 	docsCmd.AddCommand(docsCleanCmd)
 }
@@ -87,8 +92,14 @@ func RunCleanDocs(cmd *cobra.Command, args []string) {
 	os.Remove(filepath.Join(outputDir, "manifest.json"))
 }
 
+var openapipkg = filepath.Join("pkg", "generated", "openapi")
+
 func RunDocs(cmd *cobra.Command, args []string) {
+	// Delete old build artifacts
 	os.RemoveAll(filepath.Join(outputDir, "includes"))
+	os.RemoveAll(filepath.Join(outputDir, "build"))
+	os.Remove(filepath.Join(outputDir, "manifest.json"))
+
 	os.MkdirAll(filepath.Join(outputDir, "openapi-spec"), 0700)
 	os.MkdirAll(filepath.Join(outputDir, "static_includes"), 0700)
 	os.MkdirAll(filepath.Join(outputDir, "examples"), 0700)
@@ -99,17 +110,35 @@ func RunDocs(cmd *cobra.Command, args []string) {
 	}
 
 	if generateConfig {
+		// Regenerate the config.yaml with the table of contents
+		os.Remove(filepath.Join(outputDir, "config.yaml"))
 		CodeGenerator{}.Execute(wd)
 	}
 
-	// Run the docker command to build the docs
-	c := exec.Command("docker", "run",
-		"-v", fmt.Sprintf("%s:%s", filepath.Join(wd), "/host/repo"),
-		"-e", "DOMAIN="+util.GetDomain(),
-		"-e", "DIR="+filepath.Join("src", util.Repo),
-		"-e", "OUTPUT="+outputDir,
-		"gcr.io/kubebuilder/gendocs:alpha4",
-	)
+	// Make sure to generate the openapi
+	generatecmd.Codegenerators = []string{"openapi"}
+	generatecmd.RunGenerate(cmd, args)
+
+	// Create the go program to create the swagger.json by serializing the openapi go struct
+	cr := util.GetCopyright(copyright)
+	doSwaggerGen(wd, swaggerGenTemplateArgs{
+		cr,
+		util.Repo,
+	})
+	defer func() {
+		if cleanup {
+			os.RemoveAll(filepath.Join(wd, filepath.Join("pkg", "generated")))
+			os.RemoveAll(filepath.Join(wd, outputDir, "includes"))
+			os.RemoveAll(filepath.Join(wd, outputDir, "manifest.json"))
+			os.RemoveAll(filepath.Join(wd, outputDir, "build", "documents"))
+			os.RemoveAll(filepath.Join(wd, outputDir, "build", "documents"))
+			os.RemoveAll(filepath.Join(wd, outputDir, "build", "runbrodocs.sh"))
+			os.RemoveAll(filepath.Join(wd, outputDir, "build", "node_modules", "marked", "Makefile"))
+		}
+	}()
+
+	// Run the go program to write the swagger.json output to a file
+	c := exec.Command("go", "run", filepath.Join(openapipkg, "cmd", "main.go"))
 	if verbose {
 		log.Println(strings.Join(c.Args, " "))
 		c.Stderr = os.Stderr
@@ -120,6 +149,11 @@ func RunDocs(cmd *cobra.Command, args []string) {
 		log.Fatalf("error: %v\n", err)
 	}
 
+	// Call the apidocs code generator to create the markdown files that will be converted into
+	// html
+	generatecmd.Codegenerators = []string{"apidocs"}
+	generatecmd.RunGenerate(cmd, args)
+
 	// Run the docker command to build the docs
 	c = exec.Command("docker", "run",
 		"-v", fmt.Sprintf("%s:%s", filepath.Join(wd, outputDir, "includes"), "/source"),
@@ -138,16 +172,32 @@ func RunDocs(cmd *cobra.Command, args []string) {
 		log.Fatalf("error: %v\n", err)
 	}
 
-	// Cleanup intermediate files
-	if cleanup {
-		os.RemoveAll(filepath.Join(wd, outputDir, "includes"))
-		os.RemoveAll(filepath.Join(wd, outputDir, "manifest.json"))
-		os.RemoveAll(filepath.Join(wd, outputDir, "openapi-spec"))
-		os.RemoveAll(filepath.Join(wd, outputDir, "build", "documents"))
-		os.RemoveAll(filepath.Join(wd, outputDir, "build", "documents"))
-		os.RemoveAll(filepath.Join(wd, outputDir, "build", "runbrodocs.sh"))
-		os.RemoveAll(filepath.Join(wd, outputDir, "build", "node_modules", "marked", "Makefile"))
-	}
-
 	fmt.Printf("Reference docs written to %s\n", filepath.Join(outputDir, "build", "index.html"))
 }
+
+// Scaffolding file for writing the openapi generated structs to a swagger.json file
+type swaggerGenTemplateArgs struct {
+	BoilerPlate string
+	Repo        string
+}
+
+// Create a go file that will take the generated openapi.go file and serialize the go structs into a swagger.json.
+func doSwaggerGen(dir string, args swaggerGenTemplateArgs) bool {
+	path := filepath.Join(dir, openapipkg, "cmd", "main.go")
+	return util.WriteIfNotFound(path, "swagger-template", swaggerGenTemplate, args)
+}
+
+var swaggerGenTemplate = `
+{{.BoilerPlate}}
+
+package main
+
+import (
+	"github.com/kubernetes-sigs/kubebuilder/pkg/docs"
+	"{{ .Repo }}/pkg/generated/openapi"
+)
+
+func main() {
+	docs.WriteOpenAPI(openapi.GetOpenAPIDefinitions)
+}
+`

build/thirdparty/linux/Dockerfile

@@ -33,16 +33,18 @@ import (
 
 var versionedAPIs []string
 var unversionedAPIs []string
-var codegenerators []string
+var Codegenerators []string
 var copyright string
 var generators = sets.String{}
 var vendorDir string
+var Docscopyright string
+var Docstitle string
 
 var generateCmd = &cobra.Command{
-	Use:   "generate",
+	Use:     "generate",
 	Aliases: []string{"generated"},
-	Short: "Run code generators.",
-	Long:  `Run code generators`,
+	Short:   "Run code generators.",
+	Long:    `Run code generators`,
 	Example: `# Run code generators.
 kubebuilder generate`,
 	Run: RunGenerate,
@@ -58,7 +60,9 @@ func AddGenerate(cmd *cobra.Command) {
 	generateCmd.Flags().StringVar(&copyright, "copyright", filepath.Join("hack", "boilerplate.go.txt"), "Location of copyright boilerplate file.")
 	generateCmd.Flags().StringVar(&vendorDir, "vendor-dir", "", "Location of directory containing vendor files.")
 	generateCmd.Flags().StringArrayVar(&versionedAPIs, "api-versions", []string{}, "API version to generate code for.  Can be specified multiple times.  e.g. --api-versions foo/v1beta1 --api-versions bar/v1  defaults to all versions found under directories pkg/apis/<group>/<version>")
-	generateCmd.Flags().StringArrayVar(&codegenerators, "generator", []string{}, "list of generators to run.  e.g. --generator kubebuilder --generator conversion Valid values: [kubebuilder,client]")
+	generateCmd.Flags().StringArrayVar(&Codegenerators, "generator", []string{}, "list of generators to run.  e.g. --generator kubebuilder --generator conversion Valid values: [kubebuilder,client,openapi]")
+	generateCmd.Flags().StringVar(&Docscopyright, "docs-copyright", "<a href=\"https://github.com/kubernetes/kubernetes\">Copyright 2018 The Kubernetes Authors.</a>", "html for the copyright text on the docs")
+	generateCmd.Flags().StringVar(&Docstitle, "docs-title", "API Reference", "title of the docs page")
 	generateCmd.AddCommand(generateCleanCmd)
 }
 
@@ -94,7 +98,7 @@ func doGen(g string) bool {
 func RunGenerate(cmd *cobra.Command, args []string) {
 	initApis()
 
-	for _, g := range codegenerators {
+	for _, g := range Codegenerators {
 		generators.Insert(strings.Replace(g, "-gen", "", -1))
 	}
 
@@ -164,7 +168,7 @@ func RunGenerate(cmd *cobra.Command, args []string) {
 		}
 	}
 
-	if generators.Has("openapi-gen") {
+	if generators.Has("openapi") {
 		apis := []string{
 			"k8s.io/apimachinery/pkg/apis/meta/v1",
 			"k8s.io/apimachinery/pkg/api/resource",
@@ -191,7 +195,7 @@ func RunGenerate(cmd *cobra.Command, args []string) {
 				"-o", util.GoSrc,
 				"--go-header-file", copyright,
 				"-i", strings.Join(apis, ","),
-				"--output-package", filepath.Join(util.Repo, "pkg", "openapi"))...,
+				"--output-package", filepath.Join(util.Repo, "pkg", "generated", "openapi"))...,
 		)
 		glog.V(4).Infof("%s\n", strings.Join(c.Args, " "))
 		out, err := c.CombinedOutput()
@@ -200,6 +204,20 @@ func RunGenerate(cmd *cobra.Command, args []string) {
 		}
 	}
 
+	// Generate reference documentation
+	if generators.Has("apidocs") {
+		c := exec.Command(filepath.Join(root, "gen-apidocs"),
+			"--copyright", Docscopyright,
+			"--title", Docstitle,
+			"--config-dir", "docs/reference/",
+		)
+		glog.V(4).Infof("%s\n", strings.Join(c.Args, " "))
+		out, err := c.CombinedOutput()
+		if err != nil {
+			glog.Fatalf("failed to run gen-apidocs %s %v", out, err)
+		}
+	}
+
 	if generators.Has("defaulter-gen") {
 		c := exec.Command(filepath.Join(root, "defaulter-gen"),
 			append(all,

cmd/kubebuilder/docs/docs.go

@@ -0,0 +1,48 @@
+/*
+Copyright 2018 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package docs
+
+import (
+	"encoding/json"
+	"fmt"
+	"io/ioutil"
+	"log"
+	"path/filepath"
+	"strings"
+
+	"github.com/go-openapi/spec"
+	"k8s.io/kube-openapi/pkg/common"
+)
+
+// WriteOpenAPI writes the openapi json to docs/reference/openapi-spec/swagger.json
+func WriteOpenAPI(openapi func(ref common.ReferenceCallback) map[string]common.OpenAPIDefinition) {
+	defs := openapi(func(name string) spec.Ref {
+		parts := strings.Split(name, "/")
+		return spec.MustCreateRef(fmt.Sprintf("#/definitions/%s.%s",
+			common.EscapeJsonPointer(parts[len(parts)-2]),
+			common.EscapeJsonPointer(parts[len(parts)-1])))
+	})
+
+	o, err := json.MarshalIndent(defs, "", "    ")
+	if err != nil {
+		log.Fatalf("Could not Marshal JSON %v\n%v", err, defs)
+	}
+	err = ioutil.WriteFile(filepath.Join("docs", "reference", "openapi-spec", "swagger.json"), o, 0700)
+	if err != nil {
+		log.Fatalf("%v", err)
+	}
+}