docs(cli): auto-generate CLI reference from Cobra#43
Merged
Conversation
Add tools/docs-gen which walks the skillsctl Cobra tree and emits one Markdown file per command under docs/site/content/cli/reference/. The generator runs in the Docs workflow before 'hugo --minify', so the published site always matches the current release. Generated files are gitignored (only _index.md is checked in) - the source of truth lives in cli/cmd/ and the CI job materializes them at build time. Hand-written pages under docs/site/content/cli/ continue to cover prose and worked examples. Closes #41
The package had exactly one caller — its own test — and duplicated the viper wiring already in cli/cmd/root.go. Its TestDefaults failed locally any time the user had a real config at ~/.config/skillsctl/config.yaml, since viper's global singleton read the on-disk file even when the test expected defaults. The code it 'provides' still exists in root.go where it is actually used. Deleting removes the drift surface and the flaky test.
- Require -o explicitly and reject positional args; the old relative default would silently write to the wrong place when run outside the repo root. - Factor run() out of main() and add a table-driven golden test that verifies the expected files, Hugo frontmatter, and that DisableAutoGenTag suppresses the spf13/cobra stamp. - Point the Docs workflow's setup-go at root go.mod (bumped from 1.25.7 to 1.25.8 to satisfy the docs/site Hugo module). This puts docs-gen's toolchain on the same pin as every other Go job and removes the accidental coupling where Hugo's go.mod was driving the root compile. - Narrow the docs workflow's paths trigger from cli/** to cli/cmd/**; internal packages do not affect the generated reference.
This was referenced Apr 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
tools/docs-genwhich walks the skillsctl Cobra tree and emits per-command Markdown underdocs/site/content/cli/reference/..github/workflows/docs.ymlso every push builds the reference fresh beforehugo --minify. Generated files are gitignored; only_index.mdis checked in.docs/site/content/cli/*.md(with prose and worked examples) are untouched.cli/internal/configpackage. It had one caller (its own test) and duplicated the viper wiring already incli/cmd/root.go. Its TestDefaults also failed any time a real config file existed at~/.config/skillsctl/config.yamlbecause viper's global singleton picked it up. Net -73 lines.Closes #41.
Test plan