docsgen

Documentation

Overview

Package docsgen generates per-package README.md files from Go doc comments (MC-11, model A: fully generated, no marker regions). Each README carries the package doc comment plus link-outs to pkg.go.dev (the canonical API reference for a public Go module) and to the project wiki (narrative/rationale). It never touches the module's own root README.md, which is hand-authored.

Index

• func Generate(root string, cfg Config) error
• func Run(args []string, stdout, stderr io.Writer) error
• type Config

Functions

func Generate

func Generate(root string, cfg Config) error

Generate walks root's module and writes a README.md alongside every documented package: an importable package (excluding cmd/, internal/, examples/, testdata, and the module root itself) with a package doc comment and at least one exported identifier. Output is deterministic: identical input yields byte-identical output across runs.

func Run

func Run(args []string, stdout, stderr io.Writer) error

Run is cmd/docsgen's entry point, factored out here so it's covered by this package's tests: main() is reduced to a thin call-and-exit wrapper. It parses args (as os.Args[1:]) into a Config and calls Generate; verbose log lines go to stdout, flag-parse errors to stderr.

Types

type Config

type Config struct {
	// WikiBaseURL is the base URL used for each package's wiki guide
	// link-out. When empty, it is derived from the module path (assumed
	// github.com/<org>/<repo>): https://github.com/<org>/<repo>/wiki.
	WikiBaseURL string

	// Logf, when set, receives one line per documented or skipped
	// package. Skips are logged with a reason.
	Logf func(format string, args ...any)
}

Config controls docsgen's generation behavior.