Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

Generating documentation (Markdown, PlantUML) #4123

Unanswered
Discussion options

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?

You must be logged in to vote

Replies: 1 comment

Comment options

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
}
You must be logged in to vote
0 replies
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
1 participant

AltStyle によって変換されたページ (->オリジナル) /