DX: generate default yaml, including help docs from code

[jondot]

Configuration source of truth is at the Rust code. Today, we hold some defaults in a predefined YAML file, but not in the code, and the explanations are on top of each YAML field.

We should attempt for Config to describe:

• Defaults
• Documentation

Taking effect of defaults is not tied strongly to describing defaults. Users should always see all values in the generated YAML and their effective defaults INSTEAD of doing a "impl default" and magically setting defaults for users if they are not specified.

The opinion here, which is similar to Rails:

Configuration files should be self-describing.

[jondot]

This fits the concept: https://github.com/LukasKalbertodt/confique, but we have 2 challenges:

1. Our config files are actually templates, and generating them wouldn't be possible
2. Pre-rendering template files and passing them to the library, it needs files, not strings

Some more findings:

• Plain serde doesn't work. Doc comments are not transferred while serializing.
• In theory it should be possible to encode docs as a serde attribute and then have them while serializing. no builtin solution for YAML here

Pragmatic option:

Stick to rust docs. Document the entire Config hierarchy as much as possible, then Rust becomes source of truth, with these paths:

Rust -> Website
rustdoc generate a single page just out of the config tree. Use that single page as source, scape it and style it into our website docs.

Rust -> example yaml in starters
No automatic solution here. We will have to hand-maintain a documented YAML. A small 'win' here is that this configuration file can no be partially describing (we send the user to read the docs to see all options available).

Rust -> Rustdocs
For those preferring, this is a direct conversion that we can offer as part of the rest of our rust docs

[jondot]

Summary:

• YAML in Rust is seen as a data transport format, and not a configuration file. This is why comments get lost in ser/de, and refused to be supported: ymlfxr removes comments from yaml files xbcsmith/ymlfxr#2
• TOML suffers from the same thing, but has toml_edit which Cargo uses to edit TOML, which preserves comments. Here Serialize doc comments toml-rs/toml#376 (comment) is a solution for combining a library that gives access to doc comments on structs, toml_edit and toml serde. However this solution isn't recursive or works on every scenario and will require manual traversal of our entire config tree + a move to toml to support comments

All in all, I'm closing this one after:

• Covering all config fields and structs with rust docs
• Adding a guideline for contributing to configuration
• Accepting that each starter has to have its own specialized default config -- and some of the starters indeed share defaults
• Sync'ing configuration between rust, and the yaml files in each starter will have be be mindful (non automatic) and manual
• Documenting configuration in the website will resort to "document important big concepts, then refer to docs.rs for detail" which is not ideal, but saves one more big manual work of -- yet again -- writing the same docs from the Rust structs in a new format in the website