diff --git a/.prettierignore b/.prettierignore index 35f58a1f..5fc75845 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,7 +1,11 @@ -# Auto-generated by `hivectl markdown-docs` — do not format. -# The hivectl-docs CI check diffs this against fresh binary output, -# so reformatting it would break that check. +# Generated by ` markdown-docs` — do not format. The matching +# *-docs-fresh check in nix/checks.nix diffs each against fresh binary +# output, so any reformatting fails that check permanently: the +# generator, not the formatter, owns these files' layout. Every CLI +# reference doc belongs here — adding one and forgetting this line is +# what made swarmctl's fail. docs/tools/hivectl-cli.md +docs/tools/swarmctl-cli.md # Files with multi-line list-item continuations that prettier strips to col 0. # prettier's `proseWrap: "preserve"` prevents prose reflow but not list-item diff --git a/docs/tools/swarmctl-cli.md b/docs/tools/swarmctl-cli.md index 6b9c673f..1da3e791 100644 --- a/docs/tools/swarmctl-cli.md +++ b/docs/tools/swarmctl-cli.md @@ -4,12 +4,12 @@ This document contains the help content for the `swarmctl` command-line program. **Command Overview:** -- [`swarmctl`↴](#swarmctl) -- [`swarmctl user`↴](#swarmctl-user) -- [`swarmctl user add`↴](#swarmctl-user-add) -- [`swarmctl user update`↴](#swarmctl-user-update) -- [`swarmctl user list`↴](#swarmctl-user-list) -- [`swarmctl completions`↴](#swarmctl-completions) +* [`swarmctl`↴](#swarmctl) +* [`swarmctl user`↴](#swarmctl-user) +* [`swarmctl user add`↴](#swarmctl-user-add) +* [`swarmctl user update`↴](#swarmctl-user-update) +* [`swarmctl user list`↴](#swarmctl-user-list) +* [`swarmctl completions`↴](#swarmctl-completions) ## `swarmctl` @@ -19,15 +19,17 @@ swarm-level operator CLI ###### **Subcommands:** -- `user` — Manage subjects in the swarm's SSO provider -- `completions` — Generate a shell completion script for `swarmctl` and print it to stdout +* `user` — Manage subjects in the swarm's SSO provider +* `completions` — Generate a shell completion script for `swarmctl` and print it to stdout ###### **Options:** -- `--authelia-bin ` — authelia binary used to hash passwords. The argon2 parameters must match the verifier's, so this has to be the _configured_ package rather than whatever is on `PATH` -- `--users-file ` — Host-side path of authelia's users database — i.e. the path inside the container, prefixed with the container's root. +* `--authelia-bin ` — authelia binary used to hash passwords. The argon2 parameters must match the verifier's, so this has to be the *configured* package rather than whatever is on `PATH` +* `--users-file ` — Host-side path of authelia's users database — i.e. the path inside the container, prefixed with the container's root. + + This is the only user store: it is read before every change and written in place, and `swarm-authelia-bridge` writes the same file. + - This is the only user store: it is read before every change and written in place, and `swarm-authelia-bridge` writes the same file. ## `swarmctl user` @@ -37,9 +39,11 @@ Manage subjects in the swarm's SSO provider ###### **Subcommands:** -- `add` — Add a user, generating a password for them -- `update` — Change an existing user's attributes -- `list` — List every user in authelia's users database +* `add` — Add a user, generating a password for them +* `update` — Change an existing user's attributes +* `list` — List every user in authelia's users database + + ## `swarmctl user add` @@ -49,13 +53,15 @@ Add a user, generating a password for them ###### **Arguments:** -- `` — Login name. Conservative ASCII only — it is a YAML map key and reaches access-control rules and logs +* `` — Login name. Conservative ASCII only — it is a YAML map key and reaches access-control rules and logs ###### **Options:** -- `--display-name ` — Name shown in the SSO UI. Defaults to the username -- `--email
` -- `--group ` — Repeatable +* `--display-name ` — Name shown in the SSO UI. Defaults to the username +* `--email
` +* `--group ` — Repeatable + + ## `swarmctl user update` @@ -67,14 +73,16 @@ Every flag is optional and they compose, so one call can set several things at o ###### **Arguments:** -- `` — Login name of an existing user +* `` — Login name of an existing user ###### **Options:** -- `--display-name ` — Name shown in the SSO UI -- `--email
` -- `--add-group ` — Repeatable. Adding a group the user is already in is not an error -- `--remove-group ` — Repeatable. Fails if the user is not in the group — a revocation that reports success without revoking is the failure nobody re-checks +* `--display-name ` — Name shown in the SSO UI +* `--email
` +* `--add-group ` — Repeatable. Adding a group the user is already in is not an error +* `--remove-group ` — Repeatable. Fails if the user is not in the group — a revocation that reports success without revoking is the failure nobody re-checks + + ## `swarmctl user list` @@ -84,6 +92,8 @@ Read-only: it never writes the file. Shows every subject in it, including agent **Usage:** `swarmctl user list` + + ## `swarmctl completions` Generate a shell completion script for `swarmctl` and print it to stdout. @@ -96,13 +106,16 @@ Dispatched before `PathArgs::resolve()` for the same reason as `markdown-docs`: ###### **Arguments:** -- `` — Shell to emit completions for +* `` — Shell to emit completions for Possible values: `bash`, `elvish`, `fish`, `powershell`, `zsh` + + +
-This document was generated automatically by -clap-markdown. + This document was generated automatically by + clap-markdown. diff --git a/nix/checks.nix b/nix/checks.nix index 584ee408..662c44aa 100644 --- a/nix/checks.nix +++ b/nix/checks.nix @@ -209,6 +209,9 @@ in # committed copy drifted — so a verb / flag / help-string edit # that forgets to refresh the doc is caught in CI. Reuses the # already-built `packages..default` (no extra compile). + # A doc guarded this way must also be listed in `.prettierignore`: + # the generator owns its layout, and a formatter that rewrites it + # makes this check unsatisfiable rather than merely stale. # Regenerate locally with: # nix build .#default # ./result/bin/hivectl markdown-docs > docs/tools/hivectl-cli.md