feat: Generate source plugin docs (#47)

* Generate source plugin docs

Author: hermanschaaf

docs/source.go

@@ -0,0 +1,72 @@
+// Package docs helps create plugin documentation
+package docs
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"text/template"
+
+	"github.com/cloudquery/plugin-sdk/plugins"
+	"github.com/cloudquery/plugin-sdk/schema"
+)
+
+const tableTmpl = `
+# Table: {{.Name}}
+{{ $.Description }}
+## Columns
+| Name        | Type           | Description  |
+| ------------- | ------------- | -----  |
+{{- range $column := $.Columns }}
+|{{$column.Name}}|{{$column.Type | formatType}}|{{$column.Description|removeLineBreaks}}|
+{{- end }}
+`
+
+// GenerateSourcePluginDocs creates table documentation for the source plugin based on its list of tables
+func GenerateSourcePluginDocs(p *plugins.SourcePlugin, 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
+		}
+	}
+	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 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()
+	return t.Execute(f, table)
+}
+
+func formatType(v schema.ValueType) string {
+	return strings.TrimPrefix(v.String(), "Type")
+}

docs/source_test.go

@@ -0,0 +1,112 @@
+package docs
+
+import (
+	"context"
+	"io/ioutil"
+	"os"
+	"path"
+	"testing"
+
+	"github.com/cloudquery/plugin-sdk/plugins"
+	"github.com/cloudquery/plugin-sdk/schema"
+	"github.com/cloudquery/plugin-sdk/specs"
+	"github.com/google/go-cmp/cmp"
+	"github.com/rs/zerolog"
+)
+
+type testExecutionClient struct {
+	logger zerolog.Logger
+}
+
+var testTables = []*schema.Table{
+	{
+		Name:        "test_table",
+		Description: "Description for test table",
+		Columns: []schema.Column{
+			{
+				Name:        "int_col",
+				Type:        schema.TypeInt,
+				Description: "Int column",
+			},
+		},
+		Relations: []*schema.Table{
+			{
+				Name:        "relation_table",
+				Description: "Description for relational table",
+				Columns: []schema.Column{
+					{
+						Name:        "string_col",
+						Type:        schema.TypeString,
+						Description: "String column",
+					},
+				},
+			},
+		},
+	},
+}
+
+var expectFiles = []struct {
+	Name    string
+	Content string
+}{
+	{
+		Name: "test_table.md",
+		Content: `
+# Table: test_table
+Description for test table
+## Columns
+| Name        | Type           | Description  |
+| ------------- | ------------- | -----  |
+|int_col|Int|Int column|
+|_cq_id|UUID|Internal CQ ID of the row|
+|_cq_fetch_time|Timestamp|Internal CQ row of when fetch was started (this will be the same for all rows in a single fetch)|
+`,
+	},
+	{
+		Name: "relation_table.md",
+		Content: `
+# Table: relation_table
+Description for relational table
+## Columns
+| Name        | Type           | Description  |
+| ------------- | ------------- | -----  |
+|string_col|String|String column|
+|_cq_id|UUID|Internal CQ ID of the row|
+|_cq_fetch_time|Timestamp|Internal CQ row of when fetch was started (this will be the same for all rows in a single fetch)|
+`,
+	},
+}
+
+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)
+	if err != nil {
+		t.Fatalf("unexpected error calling GenerateSourcePluginDocs: %v", err)
+	}
+
+	for _, exp := range expectFiles {
+		output := path.Join(tmpdir, exp.Name)
+		got, err := ioutil.ReadFile(output)
+		if err != nil {
+			t.Fatalf("error reading %q: %v ", exp.Name, err)
+		}
+
+		if diff := cmp.Diff(string(got), exp.Content); diff != "" {
+			t.Errorf("Generate docs for %q not as expected (+got, -want): %v", exp.Name, diff)
+		}
+	}
+}

schema/md_docs.go

@@ -3,12 +3,12 @@ package serve
 import (
 	"fmt"
 
-	"github.com/cloudquery/plugin-sdk/schema"
+	"github.com/cloudquery/plugin-sdk/docs"
 	"github.com/spf13/cobra"
 )
 
 const (
-	docShort = "Generate markdown documentation for table"
+	docShort = "Generate markdown documentation for tables"
 )
 
 func newCmdDoc(opts Options) *cobra.Command {
@@ -22,7 +22,7 @@ func newCmdDoc(opts Options) *cobra.Command {
 				return fmt.Errorf("doc generation is only supported for source plugins")
 			}
 
-			return schema.GenerateMarkdownTree(opts.SourcePlugin.Tables(), args[0])
+			return docs.GenerateSourcePluginDocs(opts.SourcePlugin, args[0])
 		},
 	}
 }