Generating documentation (Markdown, PlantUML)

[jonathangjertsen]

Hi, any thoughts on generating documentation with sqlc such as Markdown documents or PlantUML entity relationhsip diagrams. Is that something that could be added to sqlc proper, or would it have to be a third-party plugin?

[jonathangjertsen]

For inspiration, here is a script I wrote to generate a Markdown document from the JSON file that sqlc already creates.

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"os"
	"path/filepath"
	"runtime/debug"
	"strings"
)

type SQLCOutput struct {
	Catalog struct {
		Schemas []struct {
			Tables []struct {
				Doc string `json:"comment"`
				Rel struct {
					Name string `json:"name"`
				} `json:"rel"`
				Columns []struct {
					Name    string `json:"name"`
					NotNull bool   `json:"not_null"`
					Doc     string `json:"comment"`
					Type    struct {
						Name string `json:"name"`
					} `json:"type"`
				} `json:"columns"`
			} `json:"tables"`
		} `json:"schemas"`
	} `json:"catalog"`
}

func (doc SQLCOutput) WriteNotice(w io.Writer, input_name string) {
	info, _ := debug.ReadBuildInfo()
	module := info.Main.Path
	fmt.Fprintf(w, "Generated from %s by %s, do not edit\n\n", filepath.Base(input_name), module)
}

func (doc SQLCOutput) Markdown(w io.Writer) {
	tables := doc.Catalog.Schemas[0].Tables

	for _, table := range tables {
		fmt.Fprintf(w, "## Table `%s`\n\n%s\n\n|column|type|doc|\n|-|-|-|\n", table.Rel.Name, table.Doc)
		for _, column := range table.Columns {
			nullness := ""
			if column.NotNull {
				nullness = "NOT "
			}
			typename := strings.ToUpper(column.Type.Name)
			fmt.Fprintf(w, "|`%s`|`%s %sNULL`|%s\n", column.Name, typename, nullness, column.Doc)
		}
	}
}

func main() {
	if err := realMain(); err != nil {
		fmt.Fprintln(os.Stderr, err.Error())
		os.Exit(1)
	}
	os.Exit(0)
}

func realMain() error {
	if len(os.Args) != 2 {
		return fmt.Errorf("expect exactly 1 arg (path to SQLC generated JSON file)")
	}

	input_name := os.Args[1]
	output_name := strings.TrimSuffix(input_name, filepath.Ext(input_name)) + ".md"

	txt, err := os.ReadFile(input_name)
	if err != nil {
		return err
	}

	var parsed SQLCOutput
	if err := json.Unmarshal(txt, &parsed); err != nil {
		return fmt.Errorf("parsing JSON: %w", err)
	}

	output, err := os.Create(output_name)
	if err != nil {
		return fmt.Errorf("creating %s: %w", output_name, err)
	}
	defer output.Close()

	parsed.WriteNotice(output, input_name)
	parsed.Markdown(output)
	fmt.Printf("wrote to %s\n", output_name)
	return nil
}