Skip to content

S12: the command reference as a published docs artifact, every example run #16

Closed

Description

@david-Darkcollective

Part of #17. Design: docs/design.md §7.4.

Scope

The command's reference, published as a docs artifact with each release so the Relix site can render a Command line section from a pinned version:

  • One page per command, generated from the same picocli CommandSpec as --help and the man pages, so the three cannot drift.
  • Hand-written pages:
    • catalog discovery, overlay and trust
    • input binding
    • output formats
    • secrets and profiles
    • pipelines with jq, find and xargs
  • A machine-readable index of the pages.

Every example in those pages runs in a test here, over a fixture .relix/ tree and fixture files, comparing stdout and the exit status. The examples guard is probed by mutation when it is written.

User-facing rule: the pages state what the command does. A limitation is stated as a fact, with no promise of future work.

Dependencies

Acceptance

  • Every command has a page.
  • No internal link is broken.
  • Every example passes.

Activity

  1. added a commit that references this issue on Oct 10, 2026
    6d7a808
  2. github-actions commented on Oct 10, 2026

    @github-actions

    Done in #42, merged to develop (7a9970c).

  3. added a commit that references this issue on Oct 12, 2026
    9e396f7
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:docsThe command reference and guidesbacklogNot yet scheduledenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions