Updating doc generation to separate dev and admin commands

.gitignore

@@ -1,6 +1,7 @@
 /oc
 /clicheck
 /gendocs
+/gendocs-admin
 /genman
 /_output
-.idea/
+.idea/

Makefile

@@ -88,6 +88,10 @@ generate-docs:
 	go run ./tools/gendocs
 .PHONY: generate-docs
 
+generate-docs-admin:
+	go run ./tools/gendocs-admin
+.PHONY: generate-docs-admin
+
 generate-versioninfo:
 	SOURCE_GIT_TAG=$(SOURCE_GIT_TAG) hack/generate-versioninfo.sh
 .PHONY: generate-versioninfo

hack/clibyexample/template

@@ -1,21 +1,19 @@
 // NOTE: The contents of this file are auto-generated
+// This template is for non-admin (not 'oc adm ...') commands
+// Uses 'source,bash' for proper syntax highlighting for comments in examples
 
-[id="openshift-cli_{context}"]
-= OpenShift CLI (oc) commands
+[id="openshift-cli-developer_{context}"]
+= OpenShift CLI (oc) developer commands
 
 {{range .items}}
 
-{{if .isAdminCommand}}ifdef::openshift-enterprise,openshift-origin[] {{end}}
-
 == {{.fullName}}
 {{.description}}
 
 .Example usage
-[source,terminal,options="nowrap"]
+[source,bash,options="nowrap"]
 ----
 {{.examples}}
 ----
 
-{{if .isAdminCommand}}endif::openshift-enterprise,openshift-origin[] {{end}}
-
 {{end}}

hack/clibyexample/template-admin

@@ -0,0 +1,19 @@
+// NOTE: The contents of this file are auto-generated
+// This template is for admin ('oc adm ...') commands
+// Uses 'source,bash' for proper syntax highlighting for comments in examples
+
+[id="openshift-cli-admin_{context}"]
+= OpenShift CLI (oc) administrator commands
+
+{{range .items}}
+
+== {{.fullName}}
+{{.description}}
+
+.Example usage
+[source,bash,options="nowrap"]
+----
+{{.examples}}
+----
+
+{{end}}

tools/gendocs-admin/gen_openshift_docs_admin.go

@@ -0,0 +1,55 @@
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"io/ioutil"
+	"os"
+	"path/filepath"
+
+	"github.com/openshift/oc/pkg/cli"
+	"github.com/openshift/oc/tools/gendocs-admin/gendocs-admin"
+)
+
+func OutDir(path string) (string, error) {
+	outDir, err := filepath.Abs(path)
+	if err != nil {
+		return "", err
+	}
+
+	stat, err := os.Stat(outDir)
+	if err != nil {
+		return "", err
+	}
+
+	if !stat.IsDir() {
+		return "", fmt.Errorf("output directory %s is not a directory\n", outDir)
+	}
+	outDir = outDir + "/"
+	return outDir, nil
+}
+
+func main() {
+	path := "docs/generated/"
+	if len(os.Args) == 2 {
+		path = os.Args[1]
+	} else if len(os.Args) > 2 {
+		fmt.Fprintf(os.Stderr, "usage: %s [output directory]\n", os.Args[0])
+		os.Exit(1)
+	}
+
+	outDir, err := OutDir(path)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "failed to get output directory: %v\n", err)
+		os.Exit(1)
+	}
+
+	outFile := outDir + "oc-by-example-content-admin.adoc"
+	out := os.Stdout
+	cmd := cli.NewOcCommand(&bytes.Buffer{}, out, ioutil.Discard)
+
+	if err := gendocsadmin.GenDocsAdmin(cmd, outFile); err != nil {
+		fmt.Fprintf(os.Stderr, "failed to generate docs: %v\n", err)
+		os.Exit(1)
+	}
+}

tools/gendocs-admin/gendocs-admin/gendocs-admin.go

@@ -0,0 +1,93 @@
+package gendocsadmin
+
+import (
+	"bytes"
+	"io/ioutil"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	corev1 "k8s.io/api/core/v1"
+	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
+	"k8s.io/cli-runtime/pkg/printers"
+)
+
+type Examples []*unstructured.Unstructured
+
+func (x Examples) Len() int      { return len(x) }
+func (x Examples) Swap(i, j int) { x[i], x[j] = x[j], x[i] }
+func (x Examples) Less(i, j int) bool {
+	xi, _ := x[i].Object["fullName"].(string)
+	xj, _ := x[j].Object["fullName"].(string)
+	return xi < xj
+}
+
+func GenDocsAdmin(cmd *cobra.Command, filename string) error {
+	out := new(bytes.Buffer)
+	templateFile, err := filepath.Abs("hack/clibyexample/template-admin")
+	if err != nil {
+		return err
+	}
+	template, err := ioutil.ReadFile(templateFile)
+	if err != nil {
+		return err
+	}
+
+	output := &unstructured.UnstructuredList{}
+	output.SetGroupVersionKind(corev1.SchemeGroupVersion.WithKind("List"))
+
+	examples := extractExamples(cmd)
+	for i := range examples {
+		output.Items = append(output.Items, *examples[i])
+	}
+
+	printer, err := printers.NewGoTemplatePrinter(template)
+	if err != nil {
+		return err
+	}
+	err = printer.PrintObj(output, out)
+	if err != nil {
+		return err
+	}
+
+	outFile, err := os.Create(filename)
+	if err != nil {
+		return err
+	}
+	defer outFile.Close()
+
+	_, err = outFile.Write(out.Bytes())
+	if err != nil {
+		return err
+	}
+	return nil
+}
+
+func extractExamples(cmd *cobra.Command) Examples {
+	objs := Examples{}
+	for _, c := range cmd.Commands() {
+		if len(c.Deprecated) > 0 {
+			continue
+		}
+ 		if strings.HasPrefix(c.CommandPath(), "oc adm") {
+			objs = append(objs, extractExamples(c)...)
+		} else {
+			continue
+		}
+	}
+	if cmd.HasExample() {
+		o := &unstructured.Unstructured{
+			Object: make(map[string]interface{}),
+		}
+		o.Object["name"] = cmd.Name()
+		o.Object["fullName"] = cmd.CommandPath()
+		o.Object["description"] = cmd.Short
+		o.Object["examples"] = cmd.Example
+		objs = append(objs, o)
+	}
+	sort.Sort(objs)
+	return objs
+}

tools/gendocs/gendocs/gendocs.go

@@ -72,17 +72,16 @@ func extractExamples(cmd *cobra.Command) Examples {
 		if len(c.Deprecated) > 0 {
 			continue
 		}
-		objs = append(objs, extractExamples(c)...)
+		if strings.HasPrefix(c.CommandPath(), "oc adm") {
+			continue
+		} else {
+			objs = append(objs, extractExamples(c)...)
+		}
 	}
 	if cmd.HasExample() {
 		o := &unstructured.Unstructured{
 			Object: make(map[string]interface{}),
 		}
-		if strings.HasPrefix(cmd.CommandPath(), "oc adm") {
-			o.Object["isAdminCommand"] = true
-		} else {
-			o.Object["isAdminCommand"] = false
-		}
 		o.Object["name"] = cmd.Name()
 		o.Object["fullName"] = cmd.CommandPath()
 		o.Object["description"] = cmd.Short