sourcey godoc — Sourcey

Extracts package documentation from a Go module and writes it to a godoc.json snapshot. The snapshot makes Go API docs portable: commit it and any docs host can render a godoc tab without a Go toolchain.

Usage

sourcey godoc [--module <dir>] [--packages <patterns>] [--out <file>]

Flags

Flag	Alias	Default	Description
`--module`	`-m`	`.`	Go module directory (containing `go.mod`)
`--packages`	`-p`	`./...`	Package patterns, comma-separated
`--exclude`		none	Import-path prefixes to exclude, comma-separated
`--out`	`-o`	`godoc.json`	Output file path
`--includeTests`		`true`	Include examples from `*_test.go` files
`--includeUnexported`		`false`	Include unexported symbols
`--quiet`	`-q`	`false`	Suppress output

Behavior

The command runs the Go toolchain (go list, go/parser, go/doc) against the module and serializes the result as JSON. Go must be installed and on PATH.

sourcey godoc --module . --packages './...' --out docs/godoc.json

Sourcey: wrote godoc snapshot for github.com/acme/widgets
  Packages:    12
  Output:      /path/to/docs/godoc.json

Introspection warnings and errors are listed below the summary. The command exits 1 when any error-level diagnostic is reported.

Using the snapshot

Point a godoc tab at the committed file and set snapshot mode:

import { defineConfig, godoc } from "sourcey";

export default defineConfig({
  navigation: {
    tabs: [
      {
        tab: "Go API",
        slug: "go-api",
        source: godoc({
          snapshot: "./godoc.json",
          mode: "snapshot",
        }),
      },
    ],
  },
});

With mode: "auto" (the default), Sourcey builds live from Go source when the toolchain is available and falls back to the snapshot otherwise.

Tip

Regenerate the snapshot when the Go API changes. A CI step that runs sourcey godoc and fails on a dirty diff keeps the committed snapshot honest.

Standalone binary

Go-only teams can generate the same snapshot without Node using sourcey-godoc:

go install github.com/sourcey/sourcey/go/sourcey-godoc/cmd/sourcey-godoc@latest
sourcey-godoc snapshot --out godoc.json

See the Go / godoc guide for the full godoc tab reference.