-
Notifications
You must be signed in to change notification settings - Fork 19
Support explicit root overview metadata in OpenCLI exports #80
Problem
When rendering docs from an OpenCLI export, the root overview page has very little app-level context unless the exporter provides it explicitly.
For example, for a CLI like Jellyfin-Cli, the ideal overview starts with something like:
Manage your Jellyfin server from the command line.
and then shows the top-level command areas.
Right now, the export mainly gives command structure, descriptions, options, and examples, but not a real root/app overview. That forces downstream renderers to invent fallback text from the command tree.
Why this matters
The root page is the first thing users read. It should explain what the CLI is for before dropping into the command list.
Without explicit root-level metadata:
- generated docs feel incomplete at the top level
- renderers need heuristics to guess intent
- different renderers will likely produce inconsistent overview text
Suggested capability
It would help if OpenCLI supported explicit app-level overview metadata in the exported document, for example:
- root summary
- root description
- optionally root examples or introductory notes
Something along the lines of:
info.summaryinfo.description
or another equivalent root-level structure if that fits the spec better.
Example use case
For a Jellyfin CLI, a renderer could then show:
- Summary:
Manage your Jellyfin server from the command line. - Description: short explanation of auth, browsing, administration, raw endpoint access, etc.
- Then the linked top-level command list
Current workaround
A renderer can synthesize fallback overview text from command names and descriptions, but that is only a heuristic. It is useful as a fallback, not as the primary source of truth.
Request
Would you consider adding explicit root/app overview metadata to the OpenCLI model/export so generated documentation can produce a proper overview page without guessing?