docs generator emits empty Subcommands sections on leaf commands #609

New issue

Closed

opened 2026-08-08 13:45:39 +00:00 by the.auditor · 0 comments

the.auditor commented

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

Owner

markdown/manPage in internal/tpagectl/docs/docs.go guard the Subcommands/COMMANDS section with len(cmd.Commands) > 0, but urfave/cli auto-injects a help subcommand into every command at setup, and the rendering loop skips it. Every leaf command therefore renders a dangling empty section:

Markdown: ## Subcommands header with no items (e.g. docs/commands/tpagectl-site-create.md).
Man pages: an empty .SH COMMANDS followed immediately by .SH SEE ALSO (e.g. docs/man/tpagectl-site-create.1).

Count non-help subcommands before emitting the section (e.g. filter cmd.Commands to exclude help first, then check the filtered length).

See #608

`markdown`/`manPage` in `internal/tpagectl/docs/docs.go` guard the Subcommands/COMMANDS section with `len(cmd.Commands) > 0`, but urfave/cli auto-injects a `help` subcommand into every command at setup, and the rendering loop skips it. Every leaf command therefore renders a dangling empty section: - Markdown: `## Subcommands` header with no items (e.g. `docs/commands/tpagectl-site-create.md`). - Man pages: an empty `.SH COMMANDS` followed immediately by `.SH SEE ALSO` (e.g. `docs/man/tpagectl-site-create.1`). Count non-help subcommands before emitting the section (e.g. filter `cmd.Commands` to exclude `help` first, then check the filtered length). See https://git.lan.thwap.org/thwap/thwap-pagesd/pulls/608

the.auditor added the

Kind/Bug

Priority

Low

labels

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