Documentation site at talm.cozystack.io with a generated CLI reference

[Aleksei Sviridkin (lexfrei)]

DNS for talm.cozystack.io resolves, so here is a site to put behind it.

The README was the whole manual: 459 lines, one page, no navigation, no search, no command reference. Sections had also grown into each other, with a 1000-word block on apply-time gates sitting between "gather node information" and "apply config". This splits it into pages under docs/, built with MkDocs Material. The prose moves as-is. What changes: heading levels, one cross-reference that pointed at a section now living on another page, and warning blockquotes, which become admonitions. The README keeps the pitch, the features and the install instructions, and links out for the rest.

The CLI reference is generated from the cobra command tree. TestReferenceDocs compares the committed pages against that tree, so go test ./... fails on drift and make docs regenerates them. talm re-exports talosctl's commands, so a Talos bump moves the command surface without anyone touching talm code.

It also drops a false claim that would otherwise have been carried straight into the new docs. talm warned that --set endpoint=10.0.0.1 reads the dots as key nesting and rendered {endpoint: {10: {0: {0: 1}}}}, and told operators to use --set-string for IP, CIDR and version literals. strvals does not do that on helm v3 or v4: dots nest only on the left of the =, and the value comes through whole. So the warning fired on values that were never at risk and told operators their config was corrupt when it was not. The screen is gone, the flag help now names the real difference (integers and booleans get converted), and two tests pin the parser behaviour so the claim cannot come back.

Before merging, someone has to set the custom domain to talm.cozystack.io in Settings > Pages. There is no CNAME file, because GitHub ignores one in the artifact when publishing from a workflow, and the domain is not expressible in the workflow either. Until it is set, the 13 absolute links now in the README 404. Provisioning the Pages site itself needs no manual step, the workflow does that through configure-pages.

Worth knowing while reviewing:

• mkdocs build --strict runs on every PR with anchor, link and nav validation raised to warnings. That workflow has no paths filter on purpose: one skipped by a filter stays Pending and can never be a required check.
• go-md2man arrives as an indirect dependency of cobra/doc. It stays test-only, so the shipped binary is unchanged.
• The reference test skips on Windows. Flag defaults go through filepath.Join, so the pages render with backslashes there.

cozystack/website also documents talm under content/en/docs/*/install/kubernetes/talm.md, so the two overlap now. Nothing there links to a README anchor, so nothing breaks, but the duplication is worth a follow-up in that repo.

[coderabbitai]

Important

Review skipped

Too many files!

This PR contains 116 files, which is 16 over the limit of 100.

To get a review, reduce the PR to 100 files or fewer by splitting it into smaller PRs or changing its base branch.

Upgrade to a paid plan to raise the limit.

This review couldn't start because sufficient usage credits or metered capacity aren't available. Add credits or update usage-based reviews in the billing tab, then retry.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 2f553310-f717-464e-b174-8d420be5b8ad

📥 Commits

Reviewing files that changed from the base of the PR and between 1d571ba and b012d20.

⛔ Files ignored due to path filters (3)

• docs/assets/favicon.svg is excluded by !**/*.svg
• docs/assets/logo.svg is excluded by !**/*.svg
• go.sum is excluded by !**/*.sum

📒 Files selected for processing (116)

• .gitattributes
• .github/workflows/docs-validate.yaml
• .github/workflows/docs.yaml
• .gitignore
• Makefile
• README.md
• docs/.nav.yml
• docs/configuration/encryption.md
• docs/configuration/endpoints-and-vips.md
• docs/configuration/node-files.md
• docs/configuration/talos-versions.md
• docs/configuration/templates.md
• docs/getting-started/init.md
• docs/getting-started/installation.md
• docs/getting-started/quickstart.md
• docs/index.md
• docs/operations/safety-gates.md
• docs/operations/side-patches.md
• docs/operations/talosctl-commands.md
• docs/operations/upgrading.md
• docs/reference/.nav.yml
• docs/reference/apply.md
• docs/reference/bootstrap.md
• docs/reference/cgroups.md
• docs/reference/completion.md
• docs/reference/completion_bash.md
• docs/reference/completion_fish.md
• docs/reference/completion_powershell.md
• docs/reference/completion_zsh.md
• docs/reference/conformance.md
• docs/reference/conformance_kubernetes.md
• docs/reference/containers.md
• docs/reference/copy.md
• docs/reference/crashdump.md
• docs/reference/dashboard.md
• docs/reference/debug.md
• docs/reference/disks.md
• docs/reference/edit.md
• docs/reference/etcd.md
• docs/reference/etcd_alarm.md
• docs/reference/etcd_alarm_disarm.md
• docs/reference/etcd_alarm_list.md
• docs/reference/etcd_defrag.md
• docs/reference/etcd_downgrade.md
• docs/reference/etcd_downgrade_cancel.md
• docs/reference/etcd_downgrade_enable.md
• docs/reference/etcd_downgrade_validate.md
• docs/reference/etcd_forfeit-leadership.md
• docs/reference/etcd_leave.md
• docs/reference/etcd_members.md
• docs/reference/etcd_remove-member.md
• docs/reference/etcd_snapshot.md
• docs/reference/etcd_status.md
• docs/reference/events.md
• docs/reference/get.md
• docs/reference/health.md
• docs/reference/image.md
• docs/reference/image_cache-cert-gen.md
• docs/reference/image_cache-create.md
• docs/reference/image_cache-serve.md
• docs/reference/image_integration.md
• docs/reference/image_k8s-bundle.md
• docs/reference/image_list.md
• docs/reference/image_pull.md
• docs/reference/image_remove.md
• docs/reference/image_talos-bundle.md
• docs/reference/index.md
• docs/reference/init.md
• docs/reference/inspect.md
• docs/reference/inspect_dependencies.md
• docs/reference/interfaces.md
• docs/reference/kubeconfig.md
• docs/reference/list.md
• docs/reference/logs.md
• docs/reference/memory.md
• docs/reference/meta.md
• docs/reference/meta_delete.md
• docs/reference/meta_write.md
• docs/reference/mounts.md
• docs/reference/netstat.md
• docs/reference/pcap.md
• docs/reference/processes.md
• docs/reference/read.md
• docs/reference/reboot.md
• docs/reference/reset.md
• docs/reference/restart.md
• docs/reference/rollback.md
• docs/reference/rotate-ca.md
• docs/reference/routes.md
• docs/reference/service.md
• docs/reference/shutdown.md
• docs/reference/stats.md
• docs/reference/support.md
• docs/reference/talosconfig.md
• docs/reference/template.md
• docs/reference/time.md
• docs/reference/upgrade.md
• docs/reference/usage.md
• docs/reference/version.md
• docs/reference/wipe.md
• docs/reference/wipe_disk.md
• docs/stylesheets/extra.css
• docs_reference_test.go
• go.mod
• main.go
• mkdocs.yml
• pkg/commands/apply.go
• pkg/commands/contract_template_set_help_test.go
• pkg/commands/template.go
• pkg/commands/upgrade_handler_test.go
• pkg/engine/contract_setvalue_warning_test.go
• pkg/engine/engine.go
• pkg/engine/setvalue_test.go
• pkg/engine/setvalue_warn.go
• requirements-docs.in
• requirements-docs.txt

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[myasnikovdaniil]

APPROVE. I ran go test ./... and mkdocs build --strict, both pass. I also checked navigation, search and mobile layout in browser. Pages needs to be enabled manually with GitHub Actions as source when setting the custom domain.