rust-cli / rust-cli/config-rs

Generate user-facing documentation for a config structure

Open
#711 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

C-enhancement S-waiting-on-design
Dominant language
Rust
Stars
3.2k
Forks
265
Avg merge
2h 42m
Merged PRs (30d)
4

Description

I would like a way to generate some kind of document that can serve as a canonical reference for the config values in my app, their sources, and their defaults. This should ideally incorporate both the doc-comments from the config struct(s) deserialized from my config-builder as well as the information about defaults and priority that the builder internalizes as part of the configuration setup.

So this would need to be some kind of function or macro that takes both a (fully configured) config-builder struct and a config type, and then generates a data structure mapping the serde::Deserialize fields to any corresponding defaults and sources from the config builder, in a form that can then be used to generate e.g. a markdown table (the actual formatting doesn't need to be part of this crate as long as the data is in some kind of form that the user can work with).

Is something like this even possible? I imagine that getting the Deserialize field names at runtime might be hacky; perhaps this would need to be implemented as an "alternate deserializer" that records what fields serde checks for as it goes.

Originally posted by @BatmanAoD in https://github.com/rust-cli/config-rs/discussions/661

(opening as an issue per the request in #321)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No files or tests are identified in the issue. Start by reviewing the config-builder and config type APIs, including how serde::Deserialize fields, defaults, sources, and priority are represented. Done should be a workable design and implementation that exposes those associations in a reusable data structure suitable for user-generated documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.