Skip to content

Book: Section on config-description #167

Open

Description

@matthiasbeyer

As requested in #166 (comment) I'd like to open up a discussion about config description.

The general idea of what I call "config description" here is that a given configuration type can describe itself in a machine-readable way, which can ultimatively be rendered to user-documentation.

A user would ask the program "tell me how I can configure you?" and the program is then able to tell the user "I get configured via the following settings: 'greeting_message', which has to be a String, 'repeat', which has to be a number greater than zero".

A possible solution for this is sketched out in #166 using the type_description crate.

Activity

  1. epage commented on Sep 16, 2022

    @epage
    Contributor

    Alternatives

    • In git-fixture, I use schemars to generate a schema
    • In cargo-release, I provide a --dump-config flag to show the user all layers of the config merged
      • This is more "documentation by example"
      • Also allows the user to debug their configuration
      • Provides transparency on defaults
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

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions