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" ) typeSQLCOutputstruct{Catalogstruct{Schemas []struct{Tables []struct{Docstring`json:"comment"`Relstruct{Namestring`json:"name"` } `json:"rel"`Columns []struct{Namestring`json:"name"`NotNullbool`json:"not_null"`Docstring`json:"comment"`Typestruct{Namestring`json:"name"` } `json:"type"` } `json:"columns"` } `json:"tables"` } `json:"schemas"` } `json:"catalog"` } func (docSQLCOutput) WriteNotice(w io.Writer, input_namestring){info, _:=debug.ReadBuildInfo() module:=info.Main.Pathfmt.Fprintf(w, "Generated from %s by %s, do not edit\n\n", filepath.Base(input_name), module) } func (docSQLCOutput) Markdown(w io.Writer){tables:=doc.Catalog.Schemas[0].Tablesfor_, table:=rangetables{fmt.Fprintf(w, "## Table `%s`\n\n%s\n\n|column|type|doc|\n|-|-|-|\n", table.Rel.Name, table.Doc) for_, column:=rangetable.Columns{nullness:=""ifcolumn.NotNull{nullness="NOT " } typename:=strings.ToUpper(column.Type.Name) fmt.Fprintf(w, "|`%s`|`%s %sNULL`|%s\n", column.Name, typename, nullness, column.Doc) } } } funcmain(){iferr:=realMain(); err!=nil{fmt.Fprintln(os.Stderr, err.Error()) os.Exit(1) } os.Exit(0) } funcrealMain() error{iflen(os.Args) !=2{returnfmt.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) iferr!=nil{returnerr } varparsedSQLCOutputiferr:=json.Unmarshal(txt, &parsed); err!=nil{returnfmt.Errorf("parsing JSON: %w", err) } output, err:=os.Create(output_name) iferr!=nil{returnfmt.Errorf("creating %s: %w", output_name, err) } deferoutput.Close() parsed.WriteNotice(output, input_name) parsed.Markdown(output) fmt.Printf("wrote to %s\n", output_name) returnnil }