The final solution should be automatic to ensure correctness and that it's always up-to-date (with the GitHub workflow being probably the easiest way to accomplish that).
The easiest way to accomplish this would be to have a unit test that would read some well-known file (say, default-config.toml) and check whether a TOML file generated using serializing Config::default() is the same. Then, the file could be included in the docs using #[doc] attribute.
Bonus points for figuring out how could we improve the above in the following areas:
- Not including said file on the repo (sadly, I don't think we can use build.rs here)
- Including information on possible values (e.g. listing all the possible values for the enums)
I think, however, that even including an automatically generated Config::default() file would still be useful.
Another idea would be to use schemars and generate a TOML file using JSON schema somehow. Sounds much more complex, however.
Lastly, it might be worth looking into specialized crates such as https://crates.io/crates/confique , or https://docs.rs/setty/latest/setty/ .
The final solution should be automatic to ensure correctness and that it's always up-to-date (with the GitHub workflow being probably the easiest way to accomplish that).
The easiest way to accomplish this would be to have a unit test that would read some well-known file (say,
default-config.toml) and check whether a TOML file generated using serializingConfig::default()is the same. Then, the file could be included in the docs using#[doc]attribute.Bonus points for figuring out how could we improve the above in the following areas:
I think, however, that even including an automatically generated
Config::default()file would still be useful.Another idea would be to use
schemarsand generate a TOML file using JSON schema somehow. Sounds much more complex, however.Lastly, it might be worth looking into specialized crates such as https://crates.io/crates/confique , or https://docs.rs/setty/latest/setty/ .