Skip to content

Commit c742694

Browse files
lexfreimyasnikovdaniil
authored andcommitted
docs: generate a CLI reference from the cobra command tree
talm's only documentation was the README, which never covered the command surface: five native commands plus everything wrapped from talosctl, each with its own flags. Writing that by hand would go stale on the next Talos bump, since the wrapper re-exports whatever upstream ships. Render it instead. TestReferenceDocs walks the live command tree and compares it against the committed pages, so `go test ./...` fails when the two drift; `make docs` rewrites them. This follows the golden-file convention already used for the chart render snapshots. The pages are rendered per command rather than through doc.GenMarkdownTree, which hardcodes file names carrying a redundant talm_ prefix and opens each page at H2, leaving no H1 for a docs site to title it from. Cobra's auto-generated date stamp is also suppressed on every command, not just those with a parent, so repeated runs agree. The test skips on Windows: flag defaults are built with filepath.Join, so the rendered pages carry backslashes there and a byte comparison fails for reasons unrelated to drift. Assisted-by: LLM Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent 1d571ba commit c742694

87 files changed

Lines changed: 3569 additions & 2 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitattributes‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,8 @@ pkg/generated/** linguist-generated
2727
# not hand-edited. Marking them generated keeps the rendered YAML dumps
2828
# out of language stats and collapses them in PR diffs by default.
2929
pkg/engine/testdata/golden/** linguist-generated
30+
31+
# docs/reference/ is rendered from the cobra command tree by
32+
# `make docs`, not hand-edited. Marking it generated keeps it out of
33+
# language stats and collapses it in PR diffs by default.
34+
docs/reference/*.md linguist-generated

‎Makefile‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,11 @@ TALOS_VERSION=$(shell go list -m github.com/siderolabs/talos | awk '{sub(/^v/,
99

1010
build:
1111
go build -ldflags="-X 'main.Version=$(VERSION)'"
12+
13+
# Rewrite docs/reference/ from the cobra command tree. TestReferenceDocs
14+
# compares the committed pages against that tree on every `go test ./...`,
15+
# so run this after adding a command or bumping Talos.
16+
docs:
17+
TALM_UPDATE_DOCS=1 go test . -run TestReferenceDocs
18+
19+
.PHONY: build docs

‎docs/reference/.nav.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Pages here are generated from the cobra command tree, so the list changes
2+
# whenever a command is added — including on a Talos bump, since talm wraps
3+
# talosctl's commands. Match them by glob instead of naming each one.
4+
nav:
5+
- index.md
6+
- "*.md"

‎docs/reference/apply.md‎

Lines changed: 77 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/reference/bootstrap.md‎

Lines changed: 46 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/reference/cgroups.md‎

Lines changed: 54 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/reference/completion.md‎

Lines changed: 38 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/reference/completion_bash.md‎

Lines changed: 57 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/reference/completion_fish.md‎

Lines changed: 48 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/reference/completion_powershell.md‎

Lines changed: 45 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)