fix: small improvements to generation and documentation

Author: wtrocki

internal/doc/GeneratorOptions.go

@@ -0,0 +1,24 @@
+package doc
+
+import "github.com/spf13/cobra"
+
+// GeneratorOptions all modifiers for the generator
+type GeneratorOptions struct {
+	// Directory to write the documentation files
+	Dir string
+
+	// FileNameGenerator - provides custom file name for each documentation file
+	FileNameGenerator func(cmd *cobra.Command) string
+
+	// FilePrepender - Prepend content to the generated file (add header)
+	FilePrepender func(string) string
+
+	// LinkHandler - function to handle links that lets you to transform them to different format
+	LinkHandler func(string) string
+
+	// GenerateIndex - generate index file
+	GenerateIndex bool
+
+	// IndexLocation - name and folder of the assembly file (typically ./README.adoc)
+	IndexLocation string
+}

internal/doc/docs_index.go

@@ -1,6 +1,5 @@
 package doc
 
-// TODO remove
 import (
 	"os"
 	"text/template"

internal/doc/modular_adoc_docs.go

@@ -16,6 +16,7 @@ package doc
 
 import (
 	"bytes"
+	"errors"
 	"fmt"
 	"io"
 	"os"
@@ -198,12 +199,12 @@ func printOptions(buf *bytes.Buffer, cmd *cobra.Command) error {
 }
 
 // GenAsciidoc creates asciidocs documentation
-func GenAsciidoc(cmd *cobra.Command, w io.Writer, options *GeneratorOptions) error {
-	return GenAsciidocCustom(cmd, w, options)
+func GenAsciidoc(cmd *cobra.Command, w io.Writer) error {
+	return GenAsciidocCustom(cmd, w, func(s string) string { return s })
 }
 
 // GenAsciidocCustom creates custom asciidoc documentation
-func GenAsciidocCustom(cmd *cobra.Command, w io.Writer, options *GeneratorOptions) error {
+func GenAsciidocCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) string) error {
 	cmd.InitDefaultHelpCmd()
 	cmd.InitDefaultHelpFlag()
 
@@ -292,34 +293,17 @@ func GetShortCommandPath(c *cobra.Command) string {
 	return strings.Join(commands[1:], " ")
 }
 
-// GeneratorOptions options for the generator
-type GeneratorOptions struct {
-	// Directory to write the file to.
-	Dir string
-
-	// FileNameGenerator - provides custom file name for the file we use
-	FileNameGenerator func(cmd *cobra.Command) string
-
-	// FilePrepender - Prepend content to the generated file.
-	FilePrepender func(string) string
-
-	// LinkHandler - function to handle links
-	LinkHandler func(string) string
-
-	// GenerateIndex - generate index file
-	GenerateIndex bool
-
-	// IndexLocation - name and folder of the assembly file (typically ./README.adoc)
-	IndexLocation string
-}
-
 // GenAsciidocTree will generate a markdown page for this command and all
 // descendants in the directory given. The header may be nil.
 // This function may not work correctly if your command names have `-` in them.
 // If you have `cmd` with two subcmds, `sub` and `sub-third`,
 // and `sub` has a subcommand called `third`, it is undefined which
 // help output will be in the file `cmd-sub-third.1`.
 func GenAsciidocTree(cmd *cobra.Command, options *GeneratorOptions) error {
+	if options.Dir == "" {
+		return errors.New("dir must be specified")
+	}
+
 	if options.LinkHandler == nil {
 		options.LinkHandler = func(name string) string {
 			return name
@@ -370,5 +354,5 @@ func GenAsciidocTreeCustom(cmd *cobra.Command, options *GeneratorOptions) error
 		}
 	}
 
-	return GenAsciidocCustom(cmd, f, options)
+	return GenAsciidocCustom(cmd, f, options.LinkHandler)
 }

internal/doc/modular_adoc_docs.md

@@ -17,8 +17,8 @@ func main() {
 		Use:   "test",
 		Short: "my test program",
 	}
-	options := GeneratorOptions{
-		Dir: "/tmp/test.adoc",
+	options := doc.GeneratorOptions{
+		Dir: "/tmp/",
 	}
 	err := doc.GenAsciidocTree(cmd, options)
 	if err != nil {
@@ -29,9 +29,28 @@ func main() {
 
 That will get you a AsciiDoc document `/tmp/test.adoc`
 
-## Generating AsciiDoc TOC with support for chapters
+## Generation options
 
-TODO
+
+```golang
+	// Directory to write the documentation files
+	Dir string
+
+	// FileNameGenerator - provides custom file name for each documentation file
+	FileNameGenerator func(cmd *cobra.Command) string
+
+	// FilePrepender - Prepend content to the generated file (add header)
+	FilePrepender func(string) string
+
+	// LinkHandler - function to handle links that lets you to transform them to different format
+	LinkHandler func(string) string
+
+	// GenerateIndex - generate index file
+	GenerateIndex bool
+
+	// IndexLocation - name and folder of the assembly file (typically ./README.adoc)
+	IndexLocation string
+```	
 
 ## Generate AsciiDoc docs for the entire command tree
 
@@ -53,7 +72,9 @@ import (
 
 func main() {
 	kubectl := cmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, ioutil.Discard, ioutil.Discard)
-	err := doc.GenAsciidocTree(kubectl, "./")
+	err := doc.GenAsciidocTree(kubectl, doc.GeneratorOptions{
+		Dir: "/.",
+	})
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -78,21 +99,16 @@ This will write the AsciiDoc doc for ONLY "cmd" into the out, buffer.
 
 ## Customize the output
 
-Both `GenAsciidoc` and `GenAsciidocTree` have alternate versions with callbacks to get some control of the output:
+Both `GenAsciidocTree` GeneratorOptions object provides number of customizations we can execute.
+By default only Dir folder is required to be present.
 
 ```go
-func GenAsciidocTreeCustom(cmd *Command, dir string, filePrepender, linkHandler func(string) string) error {
-	//...
+options := doc.GeneratorOptions{
+		Dir: "/.",
 }
 ```
-
-```go
-func GenAsciidocCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string) string) error {
-	//...
-}
-```
-
-The `filePrepender` will prepend the return value given the full filepath to the rendered Asciidoc file. A common use case is to add front matter to use the generated documentation with [Hugo](http://gohugo.io/):
+ 
+The `FilePrepender` field will prepend the return value given the full filepath to the rendered Asciidoc file. A common use case is to add front matter to use the generated documentation with [Hugo](http://gohugo.io/):
 
 ```go
 const fmTemplate = `---
@@ -103,7 +119,7 @@ url: %s
 ---
 `
 
-filePrepender := func(filename string) string {
+options.FilePrepender := func(filename string) string {
 	now := time.Now().Format(time.RFC3339)
 	name := filepath.Base(filename)
 	base := strings.TrimSuffix(name, path.Ext(name))
@@ -112,11 +128,20 @@ filePrepender := func(filename string) string {
 }
 ```
 
-The `linkHandler` can be used to customize the rendered internal links to the commands, given a filename:
+The `LinkHandler` can be used to customize the rendered internal links to the commands, given a filename:
 
 ```go
-linkHandler := func(name string) string {
+options.LinkHandler := func(name string) string {
 	base := strings.TrimSuffix(name, path.Ext(name))
 	return "/commands/" + strings.ToLower(base) + "/"
 }
 ```
+
+The `FileNameGenerator` can be used to customize file names: 
+
+```go
+options.FileNameGenerator = func(c *cobra.Command) string {
+		basename := c.CommandPath() + ".adoc"
+		return filepath.Join(options.Dir, basename)
+}
+```

internal/doc/modular_adoc_docs_test.go

@@ -88,7 +88,7 @@ func TestGenMdTree(t *testing.T) {
 	options := GeneratorOptions{
 		Dir: tmpdir,
 	}
-	if err := GenAsciidocTree(c, options); err != nil {
+	if err := GenAsciidocTree(c, &options); err != nil {
 		t.Fatalf("GenAsciidocTree failed: %v", err)
 	}