Merge pull request #938 from DirectXMan12/docs/controller-gen-cli

Add controller-gen CLI options to book

Author: k8s-ci-robot

docs/book/src/SUMMARY.md

@@ -66,6 +66,8 @@
       - [Object/DeepCopy](./reference/markers/object.md)
       - [RBAC](./reference/markers/rbac.md)
 
+  - [controller-gen CLI](./reference/controller-gen.md)
+
 ---
 
 [Appendix: The TODO Landing Page](./TODO.md)

docs/book/src/reference/controller-gen.md

@@ -0,0 +1,72 @@
+# controller-gen CLI
+
+KubeBuilder makes use of a tool called
+[controller-gen](https://sigs.k8s.io/controller-tools/cmd/controller-gen)
+for generating utility code and Kubernetes YAML.  This code and config
+generation is controlled by the presence of special ["marker
+comments"](/reference/markers.md) in Go code.
+
+controller-gen is built out of different "generators" (which specify what
+to generate) and "output rules" (which specify how and where to write the
+results).
+
+Both are configured through command line options specified in [marker
+format](/reference/markers.md).
+
+For instance,
+
+```shell
+controller-gen paths=./... crd:trivialVersions=true rbac:roleName=controller-perms output:crd:artifacts:config=config/crd/bases
+```
+
+generates CRDs and RBAC, and specifically stores the generated CRD YAML in
+`config/crd/bases`.  For the RBAC, it uses the default output rules
+(`config/rbac`).  It considers every package in the current directory tree
+(as per the normal rules of the go `...` wildcard).
+
+## Generators
+
+Each different generator is configured through a CLI option.  Multiple
+generators may be used in a single invocation of `controller-gen`.
+
+{{#markerdocs CLI: generators}}
+
+## Output Rules
+
+Output rules configure how a given generator outputs its results. There is
+always one global "fallback" output rule (specified as `output:<rule>`),
+plus per-generator overrides (specified as `output:<generator>:<rule>`).
+
+<aside class="note">
+
+<h1>Default Rules</h1>
+
+When no fallback rule is specified manually, a set of default
+per-generator rules are used which result in YAML going to
+`config/<generator>`, and code staying where it belongs.
+
+The default rules are equivalent to
+`output:<generator>:artifacts:config=config/<generator>` for each
+generator.
+
+When a "fallback" rule is specified, that'll be used instead of the
+default rules.
+
+For example, if you specify `crd rbac:roleName=controller-perms
+output:crd:stdout`, you'll get CRDs on standard out, and rbac in a file in
+`config/rbac`. If you were to add in a global rule instead, like `crd
+rbac:roleName=controller-perms output:crd:stdout output:none`, you'd get
+CRDs to standard out, and everything else to /dev/null, because we've
+explicitly specified a fallback.
+
+</aside>
+
+For brevity, the per-generator output rules (`output:<generator>:<rule>`)
+are omitted below.  They are equivalent to the global fallback options
+listed here.
+
+{{#markerdocs CLI: output rules (optionally as output:<generator>:...)}}
+
+## Other Options
+
+{{#markerdocs CLI: generic}}

docs/book/src/reference/markers.md

@@ -1,7 +1,7 @@
 # Markers for Config/Code Generation
 
-KubeBuilder makes use of a tool called `controller-gen` (from
-[controller-tools](https://godoc.org/sigs.k8s.io/controller-tools)) for
+KubeBuilder makes use of a tool called
+[controller-gen](/reference/controller-gen.md) for
 generating utility code and Kubernetes YAML.  This code and config
 generation is controlled by the presence of special "marker comments" in
 Go code.

docs/book/theme/css/general.css

@@ -219,9 +219,6 @@ blockquote {
 .marker dl.args.summary dt::before {
     content: ',';
 }
-.marker dl.args.summary dt:first-of-type:last-of-type::before {
-    content: '';
-}
 /* hide in non-summary view */
 .marker dd.args {
     display: none
@@ -309,25 +306,25 @@ blockquote {
 }
 
 /* summary view */
-#markers-summarize:checked ~ dl > .marker dd.args {
+.markers-summarize:checked ~ dl > .marker dd.args {
     display: inline-block
 }
-#markers-summarize:checked ~ dl > .marker dd.description dl.args {
+.markers-summarize:checked ~ dl > .marker dd.description dl.args {
     display: none
 }
-#markers-summarize:checked ~ dl > .marker dd.description {
+.markers-summarize:checked ~ dl > .marker dd.description {
     margin-bottom: 0.25em;
 }
 
-#markers-summarize {
+input.markers-summarize {
     display: none;
 }
-label[for="markers-summarize"]::before {
+label.markers-summarize::before {
     margin-right: 0.5em;
     content: '\25bc';
     display: inline-block;
 }
-#markers-summarize:checked ~ label[for="markers-summarize"]::before {
+input.markers-summarize:checked ~ label.markers-summarize::before {
     content: '\25b6';
 }
 

docs/book/utils/markerdocs/main.go

@@ -114,8 +114,11 @@ func markerTemplate(marker *MarkerDoc) toHTML {
 // will be added to locations marked `{{#markerdocs category name}}`.
 // This allows us to put additional documentation in each category.
 type MarkerDocs struct {
-	// MarkerCategories contains the generators for which to query controller-tools.
-	MarkerGenerators []string
+	// Args contains the arguments to pass to controller-gen to get
+	// marker help JSON output.  Each key is a prefix to apply to
+	// category names (for disambiguation), and each value is an invocation
+	// of controller-gen.
+	Args map[string][]string
 }
 
 func (_ MarkerDocs) SupportsOutput(_ string) bool { return true }
@@ -128,6 +131,11 @@ func (p MarkerDocs) Process(input *plugin.Input) error {
 	// first, find all categories...
 	markersByCategory := make(map[string][]MarkerDoc)
 	for _, cat := range markerDocs {
+		if cat.Category == "" {
+			// skip un-named categories, which are intended to be hidden
+			// (e.g. all the per-generate idendical output rules)
+			continue
+		}
 		markersByCategory[cat.Category] = cat.Markers
 	}
 
@@ -145,10 +153,15 @@ func (p MarkerDocs) Process(input *plugin.Input) error {
 			return "", fmt.Errorf("unknown category %q", category)
 		}
 
+		// HTML5 says that any characters are valid in ID except for space,
+		// but may not be empty (which we prevent by skipping un-named categories):
+		// https://www.w3.org/TR/html52/dom.html#element-attrdef-global-id 
+		categoryAlias := strings.ReplaceAll(category, " ", "-")
+
 		content := new(strings.Builder)
 
 		// NB(directxman12): wrap this in a div to prevent the markdown processor from inserting extra paragraphs
-		fmt.Fprint(content, "<div><input checked type=\"checkbox\" id=\"markers-summarize\"></input><label for=\"markers-summarize\">Show Detailed Argument Help</label><dl class=\"markers\">")
+		fmt.Fprintf(content, "<div><input checked type=\"checkbox\" class=\"markers-summarize\" id=\"markers-summarize-%[1]s\"></input><label class=\"markers-summarize\" for=\"markers-summarize-%[1]s\">Show Detailed Argument Help</label><dl class=\"markers\">", categoryAlias)
 
 		// write the markers
 		for _, marker := range markers {
@@ -204,25 +217,41 @@ func wrapWithNewlines(src string) string {
 
 // getMarkerDocs fetches marker documentation from controller-gen
 func (p MarkerDocs) getMarkerDocs() ([]CategoryDoc, error) {
-	args := []string{"-wwww"} // wonderful-world-wide-web
-	args = append(args, p.MarkerGenerators...)
-	cmd := exec.Command("controller-gen", args...)
-	outRaw, err := cmd.Output()
-	if err != nil {
-		return nil, err
-	}
-
 	var res []CategoryDoc
-	if err := json.Unmarshal(outRaw, &res); err != nil {
-		return nil, err
+	for categoryPrefix, args := range p.Args {
+		cmd := exec.Command("controller-gen", args...)
+		outRaw, err := cmd.Output()
+		if err != nil {
+			return nil, err
+		}
+
+		var invocationRes []CategoryDoc
+		if err := json.Unmarshal(outRaw, &invocationRes); err != nil {
+			return nil, err
+		}
+
+		for i, category := range invocationRes {
+			// leave empty categories as-is, so that they're skipped
+			if category.Category == "" {
+				continue
+			}
+			invocationRes[i].Category = categoryPrefix + category.Category
+		}
+
+		res = append(res, invocationRes...)
 	}
 
 	return res, nil
 }
 
 func main() {
 	if err := plugin.Run(MarkerDocs{
-		MarkerGenerators: []string{"crd", "webhook", "rbac:roleName=cheddar" /* role name doesn't mean anything here */, "object"},
+		Args: map[string][]string{
+			// marker args
+			"": []string{"-wwww", "crd", "webhook", "rbac:roleName=cheddar" /* role name doesn't mean anything here */, "object"},
+			// cli options args
+			"CLI: ": []string{"-hhhh"},
+		},
 	}, os.Stdin, os.Stdout, os.Args[1:]...); err != nil {
 		log.Fatal(err.Error())
 	}