docsgen

README

docsgen

docsgen is a small Go CLI that generates the reference documentation pages under docs/reference/ by inspecting the authserver source tree. It is intentionally a thin shell: each subcommand is responsible for producing exactly one Markdown file with a stable, machine-checkable header.

Usage

Build and run from the repository root:

go run ./tools/docsgen --help
go run ./tools/docsgen all                 # generate every reference page
go run ./tools/docsgen cli                 # generate only docs/reference/cli.md
go run ./tools/docsgen http --out /tmp/out # override the output directory

Each generator writes its target file under --out (default docs/reference):

Subcommand	Output file
cli	cli.md
http	http-api.md
env	env-vars.md
config	configuration.md
all	runs all four in sequence

Every generated file starts with the canonical header:

<!-- generated by tools/docsgen; do not edit. Re-run: make docs-gen -->

make docs-check greps for this marker; do not strip it.

Repository layout

tools/docsgen/
  main.go                       # cobra entrypoint
  cmd/
    root.go                     # NewRoot wires up subcommands + --out flag
    common.go                   # writeStub helper (shared between generators)
    cli.go / http.go /
    env.go / config.go          # one file per generator subcommand
    all.go                      # `docsgen all` fan-out
  internal/
    mdwriter/                   # Markdown table/anchor/codeblock helpers
    srcref/                     # AST-position -> "file.go:LINE" formatter
  README.md                     # you are here

Adding a new generator

Adding (say) a metrics generator that produces docs/reference/metrics.md takes four steps:

1. Create tools/docsgen/cmd/metrics.go with a newMetricsCmd() factory that mirrors cli.go. It must:
   • read --out from cmd.Flags().GetString("out");
   • call writeStub(outDir, "metrics.md", "Metrics Reference", "...") for the initial scaffold; later replace the body with the real generator output;
   • return the error verbatim (cobra prints it).
2. Register it in cmd/root.go inside NewRoot():

   root.AddCommand(newMetricsCmd())
   

3. Wire it into cmd/all.go by appending newMetricsCmd() to the subs slice so docsgen all picks it up.
4. Update this README's table above and add a row in the top-level docs/reference/README.md if one exists.

When you replace the stub body with real generation logic:

• Compose Markdown via internal/mdwriter (Table, CodeBlock, Section, Anchor) rather than hand-rolled fmt.Sprintf so output stays consistent across pages.
• Use internal/srcref to embed source references; pass the repo root so paths render as internal/foo/bar.go:42.
• Always start the output with cmd.GeneratedByHeader followed by a blank line so make docs-check continues to pass.
• Make the writer idempotent: re-running docsgen all on a clean tree should produce a byte-identical diff.

Testing

go build ./tools/docsgen
go vet ./tools/docsgen/...
go test ./tools/docsgen/...

The mdwriter and srcref packages have unit tests that cover empty inputs, alignment, slug normalisation, and FileSet edge cases. The command-tree itself is exercised end-to-end by running docsgen all against a temporary directory in CI.

Documentation

Overview

Package main implements docsgen: a small CLI that generates reference documentation (CLI flags, HTTP API, environment variables, configuration) for the Authplane authserver by inspecting the source tree.

This binary is intentionally a shell. The per-generator logic ships in subsequent tickets; each subcommand currently writes a stub file with the canonical "generated-by" header plus a TODO body so that make docs-check semantics work end-to-end immediately.