New resourcesdocs generator used to generate API Reference pages in Markdown format

Author: Philippe Martin

gen-resourcesdocs/Makefile

@@ -0,0 +1,9 @@
+clean:
+	rm -rf kwebsite/content/en/docs/* kwebsite/public
+
+kwebsite: clean
+	mkdir -p kwebsite/content/en/docs
+	go run cmd/main.go kwebsite --config-dir config/v1.20/ --file api/v1.20/swagger.json --output-dir kwebsite/content/en/docs --templates ./templates
+
+copy:
+	cp -R kwebsite/content/en/docs/* ../website/content/en/docs/reference/kubernetes-api/

gen-resourcesdocs/api/v1.19/swagger.json

@@ -0,0 +1,62 @@
+package cli
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/viper"
+)
+
+const (
+	fileOption            = "file"
+	configDirOption       = "config-dir"
+	outputDirOption       = "output-dir"
+	templatesDirOption    = "templates"
+	showDefinitionsOption = "show-definitions"
+)
+
+// RootCmd defines the root cli command
+func RootCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:           "kubernetes-api-reference",
+		Short:         "K8s API documentation tools",
+		Long:          `Tool to build documentation from OpenAPI specification of the Kubernetes API`,
+		SilenceErrors: true,
+		SilenceUsage:  true,
+		PreRun: func(cmd *cobra.Command, args []string) {
+			viper.BindPFlags(cmd.Flags())
+		},
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return nil
+		},
+	}
+
+	cmd.PersistentFlags().StringP(fileOption, "f", "", "OpenAPI spec file")
+	cmd.MarkFlagRequired(fileOption)
+
+	subcommands := []func() *cobra.Command{
+		ResourceslistCmd, ShowTOCCmd, GVKeysMap, KWebsite,
+	}
+	for _, subcommand := range subcommands {
+		cmd.AddCommand(subcommand())
+	}
+
+	cobra.OnInitialize(initConfig)
+
+	viper.SetEnvKeyReplacer(strings.NewReplacer("-", "_"))
+	return cmd
+}
+
+// Run the cli
+func Run() {
+	if err := RootCmd().Execute(); err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+}
+
+func initConfig() {
+	viper.AutomaticEnv()
+}

gen-resourcesdocs/api/v1.20/swagger.json

@@ -0,0 +1,43 @@
+package cli
+
+import (
+	"fmt"
+	"sort"
+
+	"github.com/feloy/kubernetes-api-reference/pkg/kubernetes"
+	"github.com/spf13/cobra"
+)
+
+// GVKeysMap defines the `gvkeysmap` subcommand
+func GVKeysMap() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:           "gvkeysmap",
+		Short:         "show the map between group/version and definition keys",
+		Long:          "show the map between group/version and definition keys",
+		SilenceErrors: true,
+		SilenceUsage:  true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			file := cmd.Flag(fileOption).Value.String()
+			spec, err := kubernetes.NewSpec(file)
+			if err != nil {
+				return err
+			}
+			gvs := make([]string, len(spec.GVToKey))
+			i := 0
+			for gv := range spec.GVToKey {
+				gvs[i] = gv
+				i++
+			}
+			sort.Strings(gvs)
+			for _, gv := range gvs {
+				keys := spec.GVToKey[gv]
+				fmt.Printf("%s\n", gv)
+				for _, key := range keys {
+					fmt.Printf("\t%s\n", key)
+				}
+			}
+			return nil
+		},
+	}
+	return cmd
+}

gen-resourcesdocs/cmd/cli/cli.go

@@ -0,0 +1,40 @@
+package cli
+
+import (
+	"path"
+
+	"github.com/feloy/kubernetes-api-reference/pkg/config"
+	"github.com/feloy/kubernetes-api-reference/pkg/kubernetes"
+	"github.com/spf13/cobra"
+)
+
+// prepareTOC loads Spec and Toc config, and completes TOC
+// by adding associates resources and not specifed resources in TOC
+func prepareTOC(cmd *cobra.Command) (*config.TOC, error) {
+	file := cmd.Flag(fileOption).Value.String()
+	spec, err := kubernetes.NewSpec(file)
+	if err != nil {
+		return nil, err
+	}
+
+	configDir := cmd.Flag(configDirOption).Value.String()
+	toc, err := config.LoadTOC(path.Join(configDir, "toc.yaml"))
+	err = toc.PopulateAssociates(spec)
+	if err != nil {
+		return nil, err
+	}
+
+	toc.AddOtherResources(spec)
+	toc.Definitions = &spec.Swagger.Definitions
+	toc.Actions = spec.Actions
+	toc.Actions.Sort()
+
+	// TODO browse directory
+	categories, err := config.LoadCategories([]string{path.Join(configDir, "fields.yaml")})
+	if err != nil {
+		return nil, err
+	}
+	toc.Categories = categories
+
+	return toc, nil
+}

gen-resourcesdocs/cmd/cli/gvkeysmap.go

@@ -0,0 +1,48 @@
+package cli
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+)
+
+// Hugo defines the `kwebsite` subcommand
+func KWebsite() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:           "kwebsite",
+		Short:         "output specification for k/website",
+		Long:          "output the specification in a format usable for the Kubernetes website",
+		SilenceErrors: true,
+		SilenceUsage:  true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			toc, err := prepareTOC(cmd)
+			if err != nil {
+				return fmt.Errorf("Unable to load specs and/or toc config: %v", err)
+			}
+
+			outputDir := cmd.Flag(outputDirOption).Value.String()
+			templatesDir := cmd.Flag(templatesDirOption).Value.String()
+			err = toc.ToKWebsite(outputDir, templatesDir)
+			if err != nil {
+				return err
+			}
+
+			show, err := cmd.Flags().GetBool(showDefinitionsOption)
+			if err != nil {
+				return err
+			}
+			if show {
+				toc.OutputDocumentedDefinitions()
+			}
+			return nil
+		},
+	}
+	cmd.Flags().StringP(configDirOption, "c", "", "Directory containing documentation configuration")
+	cmd.MarkFlagRequired(configDirOption)
+	cmd.Flags().StringP(outputDirOption, "o", "", "Directory to write markdown files")
+	cmd.MarkFlagRequired(outputDirOption)
+	cmd.Flags().StringP(templatesDirOption, "t", "", "Directory containing go templates for output")
+	cmd.MarkFlagRequired(templatesDirOption)
+	cmd.Flags().Bool(showDefinitionsOption, false, "Show where definitions are defined on output")
+	return cmd
+}

gen-resourcesdocs/cmd/cli/helpers.go

@@ -0,0 +1,45 @@
+package cli
+
+import (
+	"fmt"
+	"sort"
+
+	"github.com/feloy/kubernetes-api-reference/pkg/kubernetes"
+	"github.com/spf13/cobra"
+)
+
+// ResourceslistCmd defines the `resourceslist` subcommand
+func ResourceslistCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:           "resourceslist",
+		Short:         "list k8s resources",
+		Long:          "list Kubernetes resources in the specification",
+		SilenceErrors: true,
+		SilenceUsage:  true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			file := cmd.Flag(fileOption).Value.String()
+			spec, err := kubernetes.NewSpec(file)
+			if err != nil {
+				return err
+			}
+
+			resources := spec.Resources
+			i := 0
+			keys := make([]string, len(*resources))
+			for k := range *resources {
+				keys[i] = k.String()
+				i++
+			}
+			sort.Strings(keys)
+			for _, k := range keys {
+				rs := (*resources)[kubernetes.APIKind(k)]
+				fmt.Println(k)
+				for _, r := range rs {
+					fmt.Println("\t" + r.GetGV())
+				}
+			}
+			return nil
+		},
+	}
+	return cmd
+}

gen-resourcesdocs/cmd/cli/kwebsite.go

@@ -0,0 +1,31 @@
+package cli
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/spf13/cobra"
+)
+
+// ShowTOCCmd defines the `showtoc` subcommand
+func ShowTOCCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:           "showtoc",
+		Short:         "show the table of contents",
+		Long:          "list the parts and chapter of the documentation",
+		SilenceErrors: true,
+		SilenceUsage:  true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			toc, err := prepareTOC(cmd)
+			if err != nil {
+				return fmt.Errorf("Unable to load specs and/or toc config: %v", err)
+			}
+			toc.ToMarkdown(os.Stdout)
+			return nil
+		},
+	}
+	cmd.Flags().StringP(configDirOption, "c", "", "Directory containing documentation configuration")
+	cmd.MarkFlagRequired(configDirOption)
+
+	return cmd
+}

gen-resourcesdocs/cmd/cli/resourceslist.go

@@ -0,0 +1,9 @@
+package main
+
+import (
+	"github.com/feloy/kubernetes-api-reference/cmd/cli"
+)
+
+func main() {
+	cli.Run()
+}