docs(tpagectl): add comprehensive documentation #608

Merged

fuzzy merged 1 commit from docs/tpagectl-documentation into main

2026-08-08 13:46:20 +00:00

automation commented

2026-08-08 13:42:29 +00:00

Owner

What

Implements Phase 8 comprehensive documentation (roadmap #280).

internal/tpagectl/docs — a documentation generator that walks the urfave/cli command tree and renders, per command, its usage line, ArgsUsage, description, options (with defaults), and subcommands. The auto-injected help flag/subcommand are excluded. Outputs:
- Markdown (#279) — one page per command via MarkdownTree (e.g. docs/commands/tpagectl-site-create.md).
- Man pages (#278) — one roff .1 page per command via ManTree, with proper .TH/.SH structure and roff escaping.
Hidden tpagectl docs command — tpagectl docs markdown DIR and tpagectl docs man DIR regenerate the docs (--help to man/markdown).
README (#277) — cmd/tpagectl/README.md covering installation, configuration (file search order, TPAGECTL_* env, precedence), authentication (login, token set/clear, keychain), TLS controls, interactive mode, output formats, exit codes, and examples for every command group, linking to the generated docs.
Committed docs — 31 Markdown pages under docs/commands/ and 31 man pages under docs/man/.

Why

Roadmap task #280, the first item in Phase 8.

Testing

docs unit tests: synthetic command tree → Markdown/ManPage include usage, flags, subcommands, and section headers; MarkdownTree/ManTree write full-path filenames (e.g. tpagectl-site-create.md, tpagectl.1)
Generated docs verified (site create page and man page render usage/options/subcommands)
go test -race ./... passes (29 packages)
golangci-lint run clean
pre-commit hooks pass (gofmt, go mod tidy, go test, trailing-whitespace, end-of-file)

Breaking Changes

None. A hidden docs command is added; normal help output is unchanged.

Notes

urfave/cli v3 ships no ToMan/ToMarkdown (unlike v2), so generation is implemented here using the v3 Flag/DocGenerationFlag interfaces.

Closes #277
Closes #278
Closes #279
Closes #280

## What Implements Phase 8 comprehensive documentation (roadmap #280). - **`internal/tpagectl/docs`** — a documentation generator that walks the urfave/cli command tree and renders, per command, its usage line, `ArgsUsage`, description, options (with defaults), and subcommands. The auto-injected `help` flag/subcommand are excluded. Outputs: - **Markdown (#279)** — one page per command via `MarkdownTree` (e.g. `docs/commands/tpagectl-site-create.md`). - **Man pages (#278)** — one roff `.1` page per command via `ManTree`, with proper `.TH/.SH` structure and roff escaping. - **Hidden `tpagectl docs` command** — `tpagectl docs markdown DIR` and `tpagectl docs man DIR` regenerate the docs (`--help` to man/markdown). - **README (#277)** — `cmd/tpagectl/README.md` covering installation, configuration (file search order, `TPAGECTL_*` env, precedence), authentication (`login`, `token set/clear`, keychain), TLS controls, interactive mode, output formats, exit codes, and examples for every command group, linking to the generated docs. - **Committed docs** — 31 Markdown pages under `docs/commands/` and 31 man pages under `docs/man/`. ## Why Roadmap task #280, the first item in Phase 8. ## Testing - [x] `docs` unit tests: synthetic command tree → `Markdown`/`ManPage` include usage, flags, subcommands, and section headers; `MarkdownTree`/`ManTree` write full-path filenames (e.g. `tpagectl-site-create.md`, `tpagectl.1`) - [x] Generated docs verified (`site create` page and man page render usage/options/subcommands) - [x] `go test -race ./...` passes (29 packages) - [x] `golangci-lint run` clean - [x] pre-commit hooks pass (gofmt, go mod tidy, go test, trailing-whitespace, end-of-file) ## Breaking Changes None. A hidden `docs` command is added; normal help output is unchanged. ## Notes urfave/cli v3 ships no `ToMan`/`ToMarkdown` (unlike v2), so generation is implemented here using the v3 `Flag`/`DocGenerationFlag` interfaces. Closes #277 Closes #278 Closes #279 Closes #280

automation added 1 commit

2026-08-08 13:42:30 +00:00

docs(tpagectl): add comprehensive documentation

Test and Release / lint (pull_request) Successful in 31s

Details

Test and Release / test (pull_request) Successful in 31s

Details

99b6cba9cd

Add a docs generator and committed documentation:

- internal/tpagectl/docs renders one Markdown page and one roff man page
  per command by walking the urfave/cli tree, covering usage, description,
  arguments, flags (with defaults), and subcommands. The auto-injected
  help flag/subcommand are excluded.
- A hidden `tpagectl docs markdown DIR` / `tpagectl docs man DIR` command
  regenerates the docs.
- cmd/tpagectl/README.md documents installation, configuration (file,
  TPAGECTL_* env, precedence), authentication, TLS controls, interactive
  mode, output formats, exit codes, and examples for every command group.
- Generated docs committed under docs/commands (31 pages) and docs/man
  (31 man pages).

Closes #277
Closes #278
Closes #279
Closes #280

fuzzy scheduled this pull request to auto merge when all checks succeed

2026-08-08 13:43:32 +00:00

the.auditor referenced this pull request

2026-08-08 13:45:39 +00:00

docs generator emits empty Subcommands sections on leaf commands #609

the.auditor approved these changes

2026-08-08 13:45:49 +00:00

the.auditor left a comment

Comprehensive and accurate documentation system. The generator walks the urfave/cli tree correctly, excludes the auto-injected help command/flag, renders proper Markdown tables and .TH/.SH man structure with roff escaping, and the hidden docs command wires up cleanly. The README is thorough and verified accurate against the code (config precedence, env vars, TLS, exit codes, status exit 0/1). Approving; one generator defect filed.

Suggestions

internal/tpagectl/docs/docs.go:111,159 – Leaf commands render an empty ## Subcommands / .SH COMMANDS section because urfave auto-injects a help subcommand into every command at setup: len(cmd.Commands) > 0 is always true, but the loop skips help. Confirmed in the committed docs (e.g. docs/commands/tpagectl-site-create.md ends with a bare ## Subcommands; docs/man/tpagectl-site-create.1 has an empty .SH COMMANDS). Filter out help before checking the length. Filed as #609.

Notes

The hidden docs command appears in the root page's Subcommands list and gets its own doc pages — hidden commands arguably shouldn't be in user-facing docs.
.SH NAME uses the space-separated full path (tpagectl site create \- ...); man -k/apropos parsing expects a single-token name first.
.TH date is hardcoded to "2026".
Committed generated docs can drift from the CLI as it evolves; consider a CI check or go:generate guard.

Praise

Clean DocGenerationFlag usage for usage text and defaults.
Man pages use proper .TH/.SH/.TP structure and consistent roff escaping of -/./\.
README examples cover every command group and link the generated docs; regenerate instructions are present.

Comprehensive and accurate documentation system. The generator walks the urfave/cli tree correctly, excludes the auto-injected `help` command/flag, renders proper Markdown tables and `.TH/.SH` man structure with roff escaping, and the hidden `docs` command wires up cleanly. The README is thorough and verified accurate against the code (config precedence, env vars, TLS, exit codes, status exit 0/1). Approving; one generator defect filed. ## Suggestions 1. `internal/tpagectl/docs/docs.go:111,159` – Leaf commands render an empty `## Subcommands` / `.SH COMMANDS` section because urfave auto-injects a `help` subcommand into every command at setup: `len(cmd.Commands) > 0` is always true, but the loop skips `help`. Confirmed in the committed docs (e.g. `docs/commands/tpagectl-site-create.md` ends with a bare `## Subcommands`; `docs/man/tpagectl-site-create.1` has an empty `.SH COMMANDS`). Filter out `help` before checking the length. Filed as #609. ## Notes - The hidden `docs` command appears in the root page's Subcommands list and gets its own doc pages — hidden commands arguably shouldn't be in user-facing docs. - `.SH NAME` uses the space-separated full path (`tpagectl site create \- ...`); `man -k`/`apropos` parsing expects a single-token name first. - `.TH` date is hardcoded to `"2026"`. - Committed generated docs can drift from the CLI as it evolves; consider a CI check or `go:generate` guard. ## Praise - Clean `DocGenerationFlag` usage for usage text and defaults. - Man pages use proper `.TH/.SH/.TP` structure and consistent roff escaping of `-`/`.`/`\`. - README examples cover every command group and link the generated docs; regenerate instructions are present.

fuzzy merged commit 99b6cba9cd into main

2026-08-08 13:46:20 +00:00

fuzzy deleted branch docs/tpagectl-documentation

2026-08-08 13:46:20 +00:00