feat(docs): Sort tables

plugins/source/.snapshots/TestGeneratePluginDocs-JSON-__tables.json

@@ -1,4 +1,42 @@
 [
+  {
+    "name": "incremental_table",
+    "description": "Description for incremental table",
+    "columns": [
+      {
+        "name": "_cq_source_name",
+        "type": "TypeString"
+      },
+      {
+        "name": "_cq_sync_time",
+        "type": "TypeTimestamp"
+      },
+      {
+        "name": "_cq_id",
+        "type": "TypeUUID"
+      },
+      {
+        "name": "_cq_parent_id",
+        "type": "TypeUUID"
+      },
+      {
+        "name": "int_col",
+        "type": "TypeInt"
+      },
+      {
+        "name": "id_col",
+        "type": "TypeInt",
+        "is_primary_key": true,
+        "is_incremental_key": true
+      },
+      {
+        "name": "id_col2",
+        "type": "TypeInt",
+        "is_incremental_key": true
+      }
+    ],
+    "relations": []
+  },
   {
     "name": "test_table",
     "description": "Description for test table",
@@ -63,7 +101,35 @@
         ],
         "relations": [
           {
-            "name": "relation_relation_table",
+            "name": "relation_relation_table_a",
+            "description": "Description for relational table's relation",
+            "columns": [
+              {
+                "name": "_cq_source_name",
+                "type": "TypeString"
+              },
+              {
+                "name": "_cq_sync_time",
+                "type": "TypeTimestamp"
+              },
+              {
+                "name": "_cq_id",
+                "type": "TypeUUID",
+                "is_primary_key": true
+              },
+              {
+                "name": "_cq_parent_id",
+                "type": "TypeUUID"
+              },
+              {
+                "name": "string_col",
+                "type": "TypeString"
+              }
+            ],
+            "relations": []
+          },
+          {
+            "name": "relation_relation_table_b",
             "description": "Description for relational table's relation",
             "columns": [
               {
@@ -121,43 +187,5 @@
         "relations": []
       }
     ]
-  },
-  {
-    "name": "incremental_table",
-    "description": "Description for incremental table",
-    "columns": [
-      {
-        "name": "_cq_source_name",
-        "type": "TypeString"
-      },
-      {
-        "name": "_cq_sync_time",
-        "type": "TypeTimestamp"
-      },
-      {
-        "name": "_cq_id",
-        "type": "TypeUUID"
-      },
-      {
-        "name": "_cq_parent_id",
-        "type": "TypeUUID"
-      },
-      {
-        "name": "int_col",
-        "type": "TypeInt"
-      },
-      {
-        "name": "id_col",
-        "type": "TypeInt",
-        "is_primary_key": true,
-        "is_incremental_key": true
-      },
-      {
-        "name": "id_col2",
-        "type": "TypeInt",
-        "is_incremental_key": true
-      }
-    ],
-    "relations": []
   }
 ]

plugins/source/.snapshots/TestGeneratePluginDocs-Markdown-README.md

@@ -2,8 +2,9 @@
 
 ## Tables
 
+- [incremental_table](incremental_table.md) (Incremental)
 - [test_table](test_table.md)
   - [relation_table](relation_table.md)
-    - [relation_relation_table](relation_relation_table.md)
+    - [relation_relation_table_a](relation_relation_table_a.md)
+    - [relation_relation_table_b](relation_relation_table_b.md)
   - [relation_table2](relation_table2.md)
-- [incremental_table](incremental_table.md) (Incremental)

plugins/source/.snapshots/TestGeneratePluginDocs-Markdown-relation_relation_table.md → plugins/source/.snapshots/TestGeneratePluginDocs-Markdown-relation_relation_table_a.md

@@ -1,4 +1,4 @@
-# Table: relation_relation_table
+# Table: relation_relation_table_a
 
 Description for relational table's relation
 

plugins/source/.snapshots/TestGeneratePluginDocs-Markdown-relation_relation_table_b.md

@@ -0,0 +1,19 @@
+# Table: relation_relation_table_b
+
+Description for relational table's relation
+
+The primary key for this table is **_cq_id**.
+
+## Relations
+
+This table depends on [relation_table](relation_table.md).
+
+## Columns
+
+| Name          | Type          |
+| ------------- | ------------- |
+|_cq_source_name|String|
+|_cq_sync_time|Timestamp|
+|_cq_id (PK)|UUID|
+|_cq_parent_id|UUID|
+|string_col|String|

plugins/source/.snapshots/TestGeneratePluginDocs-Markdown-relation_table.md

@@ -9,7 +9,8 @@ The primary key for this table is **_cq_id**.
 This table depends on [test_table](test_table.md).
 
 The following tables depend on relation_table:
-  - [relation_relation_table](relation_relation_table.md)
+  - [relation_relation_table_a](relation_relation_table_a.md)
+  - [relation_relation_table_b](relation_relation_table_b.md)
 
 ## Columns
 

plugins/source/docs.go

@@ -8,6 +8,7 @@ import (
 	"os"
 	"path/filepath"
 	"regexp"
+	"sort"
 	"strings"
 	"text/template"
 
@@ -21,19 +22,39 @@ var templatesFS embed.FS
 var reMatchNewlines = regexp.MustCompile(`\n{3,}`)
 var reMatchHeaders = regexp.MustCompile(`(#{1,6}.+)\n+`)
 
+func sortTables(tables schema.Tables) {
+	sort.SliceStable(tables, func(i, j int) bool {
+		return tables[i].Name < tables[j].Name
+	})
+
+	for _, table := range tables {
+		sortTables(table.Relations)
+	}
+}
+
+type templateData struct {
+	PluginName string
+	Tables     schema.Tables
+}
+
 // GeneratePluginDocs creates table documentation for the source plugin based on its list of tables
 func (p *Plugin) GeneratePluginDocs(dir, format string) error {
 	if err := os.MkdirAll(dir, os.ModePerm); err != nil {
 		return err
 	}
 
 	destination.SetDestinationManagedCqColumns(p.Tables())
+	sortedTables := make(schema.Tables, 0, len(p.Tables()))
+	for _, t := range p.Tables() {
+		sortedTables = append(sortedTables, t.Copy(nil))
+	}
+	sortTables(sortedTables)
 
 	switch format {
 	case "markdown":
-		return p.renderTablesAsMarkdown(dir)
+		return renderTablesAsMarkdown(dir, p.name, sortedTables)
 	case "json":
-		return p.renderTablesAsJSON(dir)
+		return renderTablesAsJSON(dir, sortedTables)
 	default:
 		return fmt.Errorf("unsupported format: %v", format)
 	}
@@ -53,17 +74,17 @@ type jsonColumn struct {
 	IsIncrementalKey bool   `json:"is_incremental_key,omitempty"`
 }
 
-func (p *Plugin) renderTablesAsJSON(dir string) error {
-	tables := p.jsonifyTables(p.Tables())
-	b, err := json.MarshalIndent(tables, "", "  ")
+func renderTablesAsJSON(dir string, tables schema.Tables) error {
+	jsonTables := jsonifyTables(tables)
+	b, err := json.MarshalIndent(jsonTables, "", "  ")
 	if err != nil {
 		return fmt.Errorf("failed to marshal tables as json: %v", err)
 	}
 	outputPath := filepath.Join(dir, "__tables.json")
 	return os.WriteFile(outputPath, b, 0644)
 }
 
-func (p *Plugin) jsonifyTables(tables schema.Tables) []jsonTable {
+func jsonifyTables(tables schema.Tables) []jsonTable {
 	jsonTables := make([]jsonTable, len(tables))
 	for i, table := range tables {
 		jsonColumns := make([]jsonColumn, len(table.Columns))
@@ -79,14 +100,14 @@ func (p *Plugin) jsonifyTables(tables schema.Tables) []jsonTable {
 			Name:        table.Name,
 			Description: table.Description,
 			Columns:     jsonColumns,
-			Relations:   p.jsonifyTables(table.Relations),
+			Relations:   jsonifyTables(table.Relations),
 		}
 	}
 	return jsonTables
 }
 
-func (p *Plugin) renderTablesAsMarkdown(dir string) error {
-	for _, table := range p.Tables() {
+func renderTablesAsMarkdown(dir string, pluginName string, tables schema.Tables) error {
+	for _, table := range tables {
 		if err := renderAllTables(table, dir); err != nil {
 			return err
 		}
@@ -99,7 +120,7 @@ func (p *Plugin) renderTablesAsMarkdown(dir string) error {
 	}
 
 	var b bytes.Buffer
-	if err := t.Execute(&b, p); err != nil {
+	if err := t.Execute(&b, templateData{PluginName: pluginName, Tables: tables}); err != nil {
 		return fmt.Errorf("failed to execute template: %v", err)
 	}
 	content := formatMarkdown(b.String())

plugins/source/docs_test.go

@@ -44,7 +44,17 @@ var testTables = []*schema.Table{
 				},
 				Relations: []*schema.Table{
 					{
-						Name:        "relation_relation_table",
+						Name:        "relation_relation_table_b",
+						Description: "Description for relational table's relation",
+						Columns: []schema.Column{
+							{
+								Name: "string_col",
+								Type: schema.TypeString,
+							},
+						},
+					},
+					{
+						Name:        "relation_relation_table_a",
 						Description: "Description for relational table's relation",
 						Columns: []schema.Column{
 							{
@@ -101,7 +111,7 @@ func TestGeneratePluginDocs(t *testing.T) {
 			t.Fatalf("unexpected error calling GeneratePluginDocs: %v", err)
 		}
 
-		expectFiles := []string{"test_table.md", "relation_table.md", "relation_relation_table.md", "incremental_table.md", "README.md"}
+		expectFiles := []string{"test_table.md", "relation_table.md", "relation_relation_table_a.md", "relation_relation_table_b.md", "incremental_table.md", "README.md"}
 		for _, exp := range expectFiles {
 			t.Run(exp, func(t *testing.T) {
 				output := path.Join(tmpdir, exp)

plugins/source/templates/all_tables.md.go.tpl

@@ -1,4 +1,4 @@
-# Source Plugin: {{.Name}}
+# Source Plugin: {{.PluginName}}
 ## Tables
 {{- range $table := $.Tables }}
 {{- template "all_tables_entry.md.go.tpl" $table}}