feat: Make GenerateSourcePluginDocs struct method (#124)

* feat: Make GenerateSourcePluginDocs struct method

Also, generate README.md with all tables
in addition to file per table.

* Update plugins/source_docs_test.go

Co-authored-by: Erez Rokah <[email protected]>

* Update plugins/source_docs_test.go

Co-authored-by: Erez Rokah <[email protected]>

* Update plugins/source_docs_test.go

Co-authored-by: Erez Rokah <[email protected]>

* fix formmating

Co-authored-by: Erez Rokah <[email protected]>

Author: yevgenypats

docs/source.go

@@ -0,0 +1,7 @@
+
+# Source Plugin: test
+## Tables
+| Name          | Description   |
+| ------------- | ------------- |
+|test_table|Description for test table|
+

plugins/.snapshots/TestGenerateSourcePluginDocs-README.md

@@ -2,7 +2,7 @@
 # Table: relation_table
 Description for relational table
 ## Columns
-| Name        | Type           |
+| Name          | Type          |
 | ------------- | ------------- |
 |string_col|String|
 |_cq_id|UUID|

…nerateSourcePluginDocs-relation_table.md …nerateSourcePluginDocs-relation_table.mddocs/.snapshots/TestGenerateSourcePluginDocs-relation_table.md renamed to plugins/.snapshots/TestGenerateSourcePluginDocs-relation_table.md docs/.snapshots/TestGenerateSourcePluginDocs-relation_table.md renamed to plugins/.snapshots/TestGenerateSourcePluginDocs-relation_table.md

@@ -2,7 +2,7 @@
 # Table: test_table
 Description for test table
 ## Columns
-| Name        | Type           |
+| Name          | Type          |
 | ------------- | ------------- |
 |int_col|Int|
 |_cq_id|UUID|

…stGenerateSourcePluginDocs-test_table.md …stGenerateSourcePluginDocs-test_table.mddocs/.snapshots/TestGenerateSourcePluginDocs-test_table.md renamed to plugins/.snapshots/TestGenerateSourcePluginDocs-test_table.md docs/.snapshots/TestGenerateSourcePluginDocs-test_table.md renamed to plugins/.snapshots/TestGenerateSourcePluginDocs-test_table.md

@@ -1 +1,97 @@
 package plugins
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"text/template"
+
+	"github.com/cloudquery/plugin-sdk/schema"
+)
+
+const tableTmpl = `
+# Table: {{.Name}}
+{{ $.Description }}
+## Columns
+| Name          | Type          |
+| ------------- | ------------- |
+{{- range $column := $.Columns }}
+|{{$column.Name}}|{{$column.Type | formatType}}|
+{{- end }}
+`
+
+const allTablesTpml = `
+# Source Plugin: {{.Name}}
+## Tables
+| Name          | Description   |
+| ------------- | ------------- |
+{{- range $table := $.Tables }}
+|{{$table.Name}}|{{$table.Description }}|
+{{- end }}
+`
+
+// GenerateSourcePluginDocs creates table documentation for the source plugin based on its list of tables
+func (p *SourcePlugin) GenerateSourcePluginDocs(dir string) error {
+	for _, table := range p.Tables() {
+		if err := renderAllTables(table, dir); err != nil {
+			fmt.Printf("render table %s error: %s", table.Name, err)
+			return err
+		}
+	}
+	t, err := template.New("").Parse(allTablesTpml)
+	if err != nil {
+		return fmt.Errorf("failed to parse template for README.md: %v", err)
+	}
+
+	outputPath := filepath.Join(dir, "README.md")
+	f, err := os.Create(outputPath)
+	if err != nil {
+		return fmt.Errorf("failed to create file %v: %v", outputPath, err)
+	}
+	defer f.Close()
+	if err := t.Execute(f, p); err != nil {
+		return fmt.Errorf("failed to execute template: %v", err)
+	}
+	return nil
+}
+
+func renderAllTables(t *schema.Table, dir string) error {
+	if err := renderTable(t, dir); err != nil {
+		return err
+	}
+	for _, r := range t.Relations {
+		if err := renderAllTables(r, dir); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func renderTable(table *schema.Table, dir string) error {
+	t := template.New("").Funcs(map[string]interface{}{
+		"formatType": formatType,
+		"removeLineBreaks": func(text string) string {
+			return strings.ReplaceAll(text, "\n", " ")
+		},
+	})
+	t, err := t.New("").Parse(tableTmpl)
+	if err != nil {
+		return fmt.Errorf("failed to parse template: %v", err)
+	}
+
+	outputPath := filepath.Join(dir, fmt.Sprintf("%s.md", table.Name))
+	f, err := os.Create(outputPath)
+	if err != nil {
+		return fmt.Errorf("failed to create file %v: %v", outputPath, err)
+	}
+	defer f.Close()
+	if err := t.Execute(f, table); err != nil {
+		return fmt.Errorf("failed to execute template: %v", err)
+	}
+	return nil
+}
+
+func formatType(v schema.ValueType) string {
+	return strings.TrimPrefix(v.String(), "Type")
+}

plugins/source_docs.go

@@ -1,23 +1,15 @@
-package docs
+package plugins
 
 import (
-	"context"
 	"os"
 	"path"
 	"testing"
 
 	"github.com/bradleyjkemp/cupaloy/v2"
-	"github.com/cloudquery/plugin-sdk/plugins"
 	"github.com/cloudquery/plugin-sdk/schema"
-	"github.com/cloudquery/plugin-sdk/specs"
-	"github.com/rs/zerolog"
 	"github.com/stretchr/testify/require"
 )
 
-type testExecutionClient struct {
-	logger zerolog.Logger
-}
-
 var testTables = []*schema.Table{
 	{
 		Name:        "test_table",
@@ -43,28 +35,20 @@ var testTables = []*schema.Table{
 	},
 }
 
-func (c *testExecutionClient) Logger() *zerolog.Logger {
-	return &c.logger
-}
-
-func newTestExecutionClient(context.Context, zerolog.Logger, specs.Source) (schema.ClientMeta, error) {
-	return &testExecutionClient{}, nil
-}
-
 func TestGenerateSourcePluginDocs(t *testing.T) {
 	tmpdir, tmpErr := os.MkdirTemp("", "docs_test_*")
 	if tmpErr != nil {
 		t.Fatalf("failed to create temporary directory: %v", tmpErr)
 	}
 	defer os.RemoveAll(tmpdir)
 
-	p := plugins.NewSourcePlugin("test", "v1.0.0", testTables, newTestExecutionClient)
-	err := GenerateSourcePluginDocs(p, tmpdir)
+	p := NewSourcePlugin("test", "v1.0.0", testTables, newTestExecutionClient)
+	err := p.GenerateSourcePluginDocs(tmpdir)
 	if err != nil {
 		t.Fatalf("unexpected error calling GenerateSourcePluginDocs: %v", err)
 	}
 
-	expectFiles := []string{"test_table.md", "relation_table.md"}
+	expectFiles := []string{"test_table.md", "relation_table.md", "README.md"}
 	for _, exp := range expectFiles {
 		t.Run(exp, func(t *testing.T) {
 			output := path.Join(tmpdir, exp)

docs/source_test.go plugins/source_docs_test.godocs/source_test.go renamed to plugins/source_docs_test.go

@@ -4,7 +4,6 @@ package serve
 import (
 	"fmt"
 
-	"github.com/cloudquery/plugin-sdk/docs"
 	"github.com/spf13/cobra"
 )
 
@@ -22,8 +21,7 @@ func newCmdDoc(opts Options) *cobra.Command {
 			if opts.SourcePlugin == nil {
 				return fmt.Errorf("doc generation is only supported for source plugins")
 			}
-
-			return docs.GenerateSourcePluginDocs(opts.SourcePlugin, args[0])
+			return opts.SourcePlugin.GenerateSourcePluginDocs(args[0])
 		},
 	}
 }