Skip to content

fix(docs): skip hidden flags and label deprecated ones - #298

Open
kai687 wants to merge 4 commits into
mainfrom
fix/docs-generator-deprecated-flags
Open

kai687 wants to merge 4 commits into
mainfrom
fix/docs-generator-deprecated-flags

Conversation

@kai687

@kai687 kai687 commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Changes

Found while reviewing the CLI docs against the code.

  • Generator: internal/docs listed every flag, including hidden ones such as the deprecated --admin-api-key, and showed --profile without its deprecation notice. Hidden flags are now skipped so the generated docs and algolia describe match --help. Visible deprecated flags render a **Deprecated:** … line, and the describe JSON gains a deprecated field. New test covers both cases.
  • Root example: algolia rules import MOVIES -f rules.json used the wrong shorthand. The flag is -F.
  • Login help: --no-browser text named SSH sessions and containers as the use case, but the callback server listens on localhost, so the URL has to be opened on the same machine. Reworded, and browserless machines are pointed to environment variables.
  • README: brew install algolia, the formula is in homebrew/core.

Regenerating the docs against this branch changes only commands/index.mdx: the example line, --admin-api-key removed, --profile gains the deprecation line. All other pages are identical.

Checks

  • go build ./...
  • go test ./internal/docs/... ./pkg/cmd/root/... ./pkg/cmd/auth/login/... ./pkg/cmd/describe/...
  • golangci-lint run on the changed packages

The file flag's shorthand is -F. The -f example fails with an unknown
shorthand flag error and is copied into the generated docs.
The generator listed every flag, including hidden ones such as the
deprecated --admin-api-key, and showed --profile without its
deprecation notice. Skip hidden flags so the docs and describe match
--help, and render the deprecation message for visible deprecated
flags. The describe output gains a deprecated field.
The help text named SSH sessions and containers as the use case, but
the callback server listens on localhost, so the URL must be opened on
the same machine. Say that, and point browserless machines to
environment variables.
The algolia formula lives in homebrew/core, so the tap path is no
longer needed.
@kai687
kai687 marked this pull request as ready for review November 20, 2026 09:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant