Skip to content

docs: add a focused guide for optional output-format dependencies #346

Description

@codeforester

Goal

Make it obvious how a consumer installs and diagnoses optional YAML or other output-format dependencies.

Background

Output-format support spans the renderer, optional extras, dependency errors, and the installed-package boundary. A first contributor should be able to improve this guidance without changing runtime behavior.

Scope

  • Add a small table mapping each optional format to its install extra and expected diagnostic.
  • Show how to choose JSON when an optional human format is unavailable.
  • Link to the public output-format exception and process-boundary documentation.
  • Keep the guidance valid for both installed consumers and source checkouts.

Acceptance criteria

  • The table matches the current package extras and public error text.
  • The fallback path is explicit and safe.
  • The guide distinguishes an unavailable optional format from an unexpected internal error.
  • The page is linked from the README or documentation index.
  • The task can be completed with documentation and focused link checks only.

Validation

  • Inspect pyproject extras and the renderer's current public message.
  • Run git diff --check.
  • Verify internal links.

Non-goals

  • Do not change package metadata or error classification.
  • Do not add dependency installation to the core runtime.
  • Do not promise formats that the repository does not support.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

area: docsDocumentation and public guidance ownership.documentationDocumentation improvementsgood first issueGood for newcomershelp wantedExtra attention is needed

Type

No type

Projects

  • Status
    Done

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions