refactor: generate mdx docs with tabs for each config option (#996)

gen/docs/gen_env.go

@@ -46,8 +46,9 @@ func generateExampleEnv() {
 func buildEnvEntry(child reflect.StructField, childValue reflect.Value, parentPath string, entries *[]EnvEntry) {
 	desc := child.Tag.Get("description")
 	tag := child.Tag.Get("yaml")
+	gen := child.Tag.Get("gen")
 
-	if tag == "-" {
+	if tag == "-" && gen != "include" {
 		return
 	}
 

gen/docs/gen_md.go

@@ -1,7 +1,6 @@
 package main
 
 import (
-	"bytes"
 	"errors"
 	"fmt"
 	"io/fs"
@@ -13,9 +12,13 @@ import (
 	"github.com/tinyauthapp/tinyauth/internal/model"
 )
 
+type ConfigOptions struct {
+	Env  string
+	Flag string
+	YAML string
+}
 type MarkdownEntry struct {
-	Env         string
-	Flag        string
+	Options     ConfigOptions
 	Description string
 	Default     any
 }
@@ -47,8 +50,9 @@ func generateMarkdown() {
 func buildMdEntry(child reflect.StructField, childValue reflect.Value, parentPath string, entries *[]MarkdownEntry) {
 	desc := child.Tag.Get("description")
 	tag := child.Tag.Get("yaml")
+	gen := child.Tag.Get("gen")
 
-	if tag == "-" {
+	if tag == "-" && gen != "include" {
 		return
 	}
 
@@ -56,9 +60,17 @@ func buildMdEntry(child reflect.StructField, childValue reflect.Value, parentPat
 
 	value := childValue.Interface()
 
+	configOptions := ConfigOptions{
+		Env:  strings.ToUpper(strings.ReplaceAll(parentPath, ".", "_")) + strings.ToUpper(child.Name),
+		Flag: fmt.Sprintf("--%s%s", strings.TrimPrefix(parentPath, "tinyauth."), strings.ToLower(child.Name)),
+	}
+
+	if tag != "-" && tag != "" {
+		configOptions.YAML = strings.TrimPrefix(parentPath, "tinyauth.") + tag
+	}
+
 	entry := MarkdownEntry{
-		Env:         strings.ToUpper(strings.ReplaceAll(parentPath, ".", "_")) + strings.ToUpper(child.Name),
-		Flag:        fmt.Sprintf("--%s%s", strings.TrimPrefix(parentPath, "tinyauth."), strings.ToLower(child.Name)),
+		Options:     configOptions,
 		Description: desc,
 	}
 
@@ -85,8 +97,9 @@ func buildMdMapEntry(child reflect.StructField, parentPath string, entries *[]Ma
 	}
 
 	tag := child.Tag.Get("yaml")
+	gen := child.Tag.Get("gen")
 
-	if tag == "-" {
+	if tag == "-" && gen != "include" {
 		return
 	}
 
@@ -106,27 +119,54 @@ func buildMdChildPath(parent string, child string) string {
 }
 
 func compileMd(entries []MarkdownEntry) []byte {
-	buffer := bytes.Buffer{}
+	buffer := strings.Builder{}
 
-	buffer.WriteString("<!--- This file is automatically generated by gen/gen_md.go. Do not edit manually. --->\n\n")
-	buffer.WriteString("# Tinyauth configuration reference\n\n")
-	buffer.WriteString("| Environment | Flag | Description | Default |\n")
-	buffer.WriteString("| - | - | - | - |\n")
+	buffer.WriteString("{/* This part is automatically generated by gen/gen_md.go in the main repository. DO NOT EDIT. */}\n\n")
+	buffer.WriteString("import { Tabs, TabItem } from '@astrojs/starlight/components';\n\n")
+	buffer.WriteString("<Tabs>\n")
 
+	renderTabItem(&buffer, entries, "Environment")
+	renderTabItem(&buffer, entries, "Flags")
+	renderTabItem(&buffer, entries, "YAML")
+
+	buffer.WriteString("</Tabs>\n")
+
+	return []byte(buffer.String())
+}
+
+func renderTabItem(buffer *strings.Builder, entries []MarkdownEntry, section string) {
+	buffer.WriteString(fmt.Sprintf("  <TabItem label=\"%s\">\n", section))
+	buffer.WriteString("    ### main\n\n")
+	buffer.WriteString("    | Option | Description | Default |\n")
+	buffer.WriteString("    | - | - | - |\n")
+
+	configType := strings.ToLower(section)
 	previousSection := ""
 
 	for _, entry := range entries {
-		if strings.Count(entry.Env, "_") > 1 {
-			section := strings.Split(strings.TrimPrefix(entry.Env, "TINYAUTH_"), "_")[0]
+		section := strings.Split(entry.Options.YAML, ".")[0]
+		var option string
+		switch configType {
+		case "yaml":
+			option = entry.Options.YAML
+		case "flags":
+			option = entry.Options.Flag
+		case "environment":
+			option = entry.Options.Env
+		}
+		if option == "" {
+			continue
+		}
+		if strings.Count(entry.Options.YAML, ".") >= 1 {
 			if section != previousSection {
-				buffer.WriteString("\n## " + strings.ToLower(section) + "\n\n")
-				buffer.WriteString("| Environment | Flag | Description | Default |\n")
-				buffer.WriteString("| - | - | - | - |\n")
+				buffer.WriteString("\n    ### " + strings.ToLower(section) + "\n\n")
+				buffer.WriteString("    | Option | Description | Default |\n")
+				buffer.WriteString("    | - | - | - |\n")
 				previousSection = section
 			}
 		}
-		fmt.Fprintf(&buffer, "| `%s` | `%s` | %s | %s |\n", entry.Env, entry.Flag, entry.Description, entry.Default)
+		fmt.Fprintf(buffer, "    | `%s` | %s | %s |\n", option, entry.Description, entry.Default)
 	}
 
-	return buffer.Bytes()
+	buffer.WriteString("  </TabItem>\n")
 }