Generating Documentation¶

The generate docs command is your secret weapon for maintaining world-class documentation with zero effort: it analyzes your Go source code with AI and produces comprehensive Markdown pages ready to serve. 📚✨

Generate docs¶

Document a command or a package — exactly one of --command / --package:

# A command (by manifest path):
go run main.go generate docs --command "az/login"

# A library package:
go run main.go generate docs --package "pkg/utils"

The sections below cover the generator's capabilities in detail.

Documentation layout (Diátaxis)¶

New projects scaffold a Diátaxis-structured docs/ tree, and generate docs places each page in the matching quadrant (for why GTB generates into this structure, see Documentation Layout):

The layout is recorded as docs_layout: diataxis in .gtb/manifest.yaml. Projects generated before this feature default to the legacy flat layout (docs/commands/, docs/packages/); run regenerate project --force to migrate them — it moves existing pages into the quadrant tree (preserving your content), updates the manifest, and removes the old trees.

Core Features¶

Portable Doc Generation 🚀¶

Documentation builds are handled by a portable Go generator. When called from a nested package (like internal/cmd/root), use the following pattern:

//go:generate go tool docs --project-root ../../.. --target-dir pkg/cmd/root/assets

This tool: - Dual Content Sync: Simultaneously synchronizes raw markdown for the TUI and builds a static site for docs serve. - Auto-Detection: Automatically uses zensical (preferred) or mkdocs if available. - Configurable: - --project-root: Point to your project sources (e.g., where zensical.toml or mkdocs.yml lives). - --target-dir: Specify where assets/docs and assets/site should be generated. - --config-file: Path to the site config file relative to the project root (default: mkdocs.yml).

Command Documentation 🕹️¶

This command:

• Agentic Inspection: Uses AI tools to explore subcommands and referenced types autonomously.
• Intelligent Formatting: Produces structured Markdown with frontmatter, usage examples, and flag tables.
• Smart Indexing: Updates the CLI reference index (docs/reference/cli/index.md) automatically. zensical projects derive site navigation from the docs tree; legacy mkdocs.yml projects get their nav list rewritten.

Package Documentation 📦¶

For developers building libraries, the --package flag generates explanation-oriented package docs (the Diátaxis explanation quadrant) — understanding, not an exhaustive API dump:

go run main.go generate docs --path . --package "pkg/utils"

The page lands in the docs/explanation/components/ hierarchy and includes:

• A high-level overview of what the package is for and the problem it solves.
• The main exported types and their roles, described narratively.
• A short usage sketch synthesized from your code.
• An API Reference pointer — by default a local go doc ./pkg/utils hint, so a private or unpublished module never gets a dead link.

Iterative Refinement 🔄¶

The AI documentation generator isn't a one-and-done tool. It respects your manual edits!

If a documentation page already exists, the AI:

1. Reads Existing Content: Uses your manual tweaks as context.
2. Preserves Customizations: Merges new technical details with your hand-written sections.
3. Maintains Authorship: Appends the AI model to the authors list while preserving existing human authors.

Advanced Usage¶

Persistent AI Configuration¶

You can easily switch between AI providers or models using persistent flags:

go run main.go generate docs --command "az/login" --provider openai --model "gpt-5.4"

Hierarchical Resolving¶

The tool intelligently resolves command paths. You can specify a deeply nested command, and the generator will find the correct source code and place the documentation in the matching folder structure.

go run main.go generate docs --command "az/keyvault/get"

Why Automated Documentation?¶

Your code is the single source of truth and the docs are its reflection — generate them as part of your workflow and keep them in sync for free. For the design and how the generator fits the framework, see the Docs component.

Focus on building great software, and let gtb handle the story of how to use it! 🚀