Merge pull request #135 from pwittrock/docs-gen

Make docs gen ordering deterministic

Author: droot

cmd/kubebuilder/docs/docs.go

@@ -61,13 +61,15 @@ var generateConfig bool
 var cleanup, verbose bool
 var outputDir string
 var copyright string
+var brodocs bool
 
 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().BoolVar(&brodocs, "brodocs", true, "Run brodocs to generate html.")
 	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)
@@ -154,25 +156,26 @@ func RunDocs(cmd *cobra.Command, args []string) {
 	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"),
-		"-v", fmt.Sprintf("%s:%s", filepath.Join(wd, outputDir, "build"), "/build"),
-		"-v", fmt.Sprintf("%s:%s", filepath.Join(wd, outputDir, "build"), "/build"),
-		"-v", fmt.Sprintf("%s:%s", filepath.Join(wd, outputDir), "/manifest"),
-		"gcr.io/kubebuilder/brodocs",
-	)
-	if verbose {
-		log.Println(strings.Join(c.Args, " "))
-		c.Stderr = os.Stderr
-		c.Stdout = os.Stdout
-	}
-	err = c.Run()
-	if err != nil {
-		log.Fatalf("error: %v\n", err)
+	if brodocs {
+		// Run the docker command to build the docs
+		c = exec.Command("docker", "run",
+			"-v", fmt.Sprintf("%s:%s", filepath.Join(wd, outputDir, "includes"), "/source"),
+			"-v", fmt.Sprintf("%s:%s", filepath.Join(wd, outputDir, "build"), "/build"),
+			"-v", fmt.Sprintf("%s:%s", filepath.Join(wd, outputDir, "build"), "/build"),
+			"-v", fmt.Sprintf("%s:%s", filepath.Join(wd, outputDir), "/manifest"),
+			"gcr.io/kubebuilder/brodocs",
+		)
+		if verbose {
+			log.Println(strings.Join(c.Args, " "))
+			c.Stderr = os.Stderr
+			c.Stdout = os.Stdout
+		}
+		err = c.Run()
+		if err != nil {
+			log.Fatalf("error: %v\n", err)
+		}
+		fmt.Printf("Reference docs written to %s\n", filepath.Join(outputDir, "build", "index.html"))
 	}
-
-	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

cmd/kubebuilder/docs/gen.go

@@ -2,14 +2,14 @@ package docs
 
 import (
 	"fmt"
+	"os"
 	"path/filepath"
 	"sort"
 	"strings"
 
 	"github.com/kubernetes-sigs/kubebuilder/cmd/internal/codegen/parse"
 	"github.com/kubernetes-sigs/kubebuilder/cmd/kubebuilder/util"
 	"k8s.io/gengo/args"
-	"os"
 )
 
 // CodeGenerator generates code for Kubernetes resources and controllers
@@ -36,7 +36,13 @@ func (g CodeGenerator) Execute(dir string) error {
 	path := filepath.Join(dir, outputDir, "config.yaml")
 
 	args := ConfigArgs{}
-	for group, kindversion := range p.ByGroupKindVersion {
+	groups := []string{}
+	for group, _ := range p.ByGroupKindVersion {
+		groups = append(groups, group)
+	}
+	sort.Strings(groups)
+	for _, group := range groups {
+		kindversion := p.ByGroupKindVersion[group]
 		args.Groups = append(args.Groups, strings.Title(group))
 		c := Category{
 			Name:    strings.Title(group),

test.sh

@@ -40,7 +40,7 @@ cd "$base_dir" || {
   exit 1
 }
 
-k8s_version=1.10
+k8s_version=1.10.1
 goarch=amd64
 goos="unknown"
 
@@ -75,6 +75,7 @@ tmp_root=/tmp
 
 kb_root_dir=$tmp_root/kubebuilder
 kb_vendor_dir=$tmp_root/vendor
+kb_orig=$(pwd)
 
 # Skip fetching and untaring the tools by setting the SKIP_FETCH_TOOLS variable
 # in your environment to any value:
@@ -160,10 +161,12 @@ function generate_crd_resources {
   kubebuilder create resource --group insect --version v1beta1 --kind Bee
 
   header_text "editing generated files to simulate a user"
-  sed -i pkg/apis/insect/v1beta1/bee_types.go -e "s|type Bee struct|// +kubebuilder:categories=foo,bar\ntype Bee struct|"
+  sed -i -e "s|type Bee struct|// +kubebuilder:categories=foo,bar\ntype Bee struct|" pkg/apis/insect/v1beta1/bee_types.go
+  sed -i -e "s|type BeeController struct {|// +kubebuilder:rbac:groups="",resources=pods,verbs=get;watch;list\ntype BeeController struct {|" pkg/controller/bee/controller.go
 
   header_text "generating and testing CRD definition"
   kubebuilder create config --crds --output crd.yaml
+  kubebuilder create config --controller-image myimage:v1 --name myextensionname --output install.yaml
 
   # Test for the expected generated CRD definition
   #
@@ -211,6 +214,166 @@ status:
 EOF
   diff crd.yaml expected.yaml
 
+    cat << EOF > expected.yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  creationTimestamp: null
+  labels:
+    api: myextensionname
+    kubebuilder.k8s.io: $INJECT_KB_VERSION
+  name: myextensionname-system
+spec: {}
+status: {}
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  creationTimestamp: null
+  labels:
+    api: myextensionname
+    kubebuilder.k8s.io: $INJECT_KB_VERSION
+  name: myextensionname-role
+rules:
+- apiGroups:
+  - ""
+  resources:
+  - pods
+  verbs:
+  - get
+  - watch
+  - list
+- apiGroups:
+  - insect.sample.kubernetes.io
+  resources:
+  - '*'
+  verbs:
+  - '*'
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  creationTimestamp: null
+  labels:
+    api: myextensionname
+    kubebuilder.k8s.io: $INJECT_KB_VERSION
+  name: myextensionname-rolebinding
+  namespace: myextensionname-system
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: myextensionname-role
+subjects:
+- kind: ServiceAccount
+  name: default
+  namespace: myextensionname-system
+---
+apiVersion: apiextensions.k8s.io/v1beta1
+kind: CustomResourceDefinition
+metadata:
+  creationTimestamp: null
+  labels:
+    api: myextensionname
+    kubebuilder.k8s.io: $INJECT_KB_VERSION
+  name: bees.insect.sample.kubernetes.io
+spec:
+  group: insect.sample.kubernetes.io
+  names:
+    categories:
+    - foo
+    - bar
+    kind: Bee
+    plural: bees
+  scope: Namespaced
+  validation:
+    openAPIV3Schema:
+      properties:
+        apiVersion:
+          type: string
+        kind:
+          type: string
+        metadata:
+          type: object
+        spec:
+          type: object
+        status:
+          type: object
+      type: object
+  version: v1beta1
+status:
+  acceptedNames:
+    kind: ""
+    plural: ""
+  conditions: null
+---
+apiVersion: v1
+kind: Service
+metadata:
+  creationTimestamp: null
+  labels:
+    api: myextensionname
+    control-plane: controller-manager
+    kubebuilder.k8s.io: $INJECT_KB_VERSION
+  name: myextensionname-controller-manager-service
+  namespace: myextensionname-system
+spec:
+  clusterIP: None
+  selector:
+    api: myextensionname
+    control-plane: controller-manager
+    kubebuilder.k8s.io: $INJECT_KB_VERSION
+status:
+  loadBalancer: {}
+---
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  creationTimestamp: null
+  labels:
+    api: myextensionname
+    control-plane: controller-manager
+    kubebuilder.k8s.io: $INJECT_KB_VERSION
+  name: myextensionname-controller-manager
+  namespace: myextensionname-system
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      api: myextensionname
+      control-plane: controller-manager
+      kubebuilder.k8s.io: $INJECT_KB_VERSION
+  serviceName: myextensionname-controller-manager-service
+  template:
+    metadata:
+      creationTimestamp: null
+      labels:
+        api: myextensionname
+        control-plane: controller-manager
+        kubebuilder.k8s.io: $INJECT_KB_VERSION
+    spec:
+      containers:
+      - args:
+        - --install-crds=false
+        command:
+        - /root/controller-manager
+        image: myimage:v1
+        name: controller-manager
+        resources:
+          limits:
+            cpu: 100m
+            memory: 30Mi
+          requests:
+            cpu: 100m
+            memory: 20Mi
+      terminationGracePeriodSeconds: 10
+  updateStrategy: {}
+status:
+  replicas: 0
+
+EOF
+  diff -B install.yaml expected.yaml
+
+
   kubebuilder create resource --group insect --version v1beta1 --kind Wasp
   kubebuilder create resource --group ant --version v1beta1 --kind Ant
   kubebuilder create config --crds --output crd.yaml
@@ -345,13 +508,22 @@ function run_dep_ensure {
  dep ensure
 }
 
+function test_docs {
+  header_text "building docs"
+  kubebuilder docs --docs-copyright "Hello" --title "World" --cleanup=false --brodocs=false
+  diff docs/reference/includes $kb_orig/test/docs/expected/includes
+  diff docs/reference/manifest.json $kb_orig/test/docs/expected/manifest.json
+  diff docs/reference/config.yaml $kb_orig/test/docs/expected/config.yaml
+}
+
 prepare_staging_dir
 fetch_tools
 build_kb
 prepare_vendor_deps
 prepare_testdir_under_gopath
 
 generate_crd_resources
+test_docs
 test_generated_controller
 run_dep_ensure
 # Run controller tests after running dep ensure because we want ensure code

test/docs/expected/config.yaml

@@ -0,0 +1,22 @@
+example_location: "examples"
+api_groups: 
+  - "Ant"
+
+  - "Insect"
+resource_categories: 
+- name: "Ant"
+  include: "ant"
+  resources: 
+  - name: "Ant"
+    version: "v1beta1"
+    group: "ant"
+
+- name: "Insect"
+  include: "insect"
+  resources: 
+  - name: "Bee"
+    version: "v1beta1"
+    group: "insect"
+  - name: "Wasp"
+    version: "v1beta1"
+    group: "insect"

test/docs/expected/includes/_ant.md

@@ -0,0 +1,5 @@
+
+# <strong>Ant</strong>
+
+------------
+

test/docs/expected/includes/_definitions.md

@@ -0,0 +1,5 @@
+
+# <strong>Field Definitions</strong>
+
+------------
+