Config documentation autogeneration #14
Description
We have multiple things which are in theory derivable from a single source of truth:
- Config example.
- Config documentation in any format.
- Config validator.
The goal is to have some "specification" together with a set of tools allowing us to generate anything we want from this spec (e.g. via Go text/template). So if we need to change anything in the config, we could alter specification and autogenerate all other pieces (xml markup for technical translators, maybe even autogenerating some ansible scripts).
I see 2 ways of writing this specification:
- JSON schema. Well-known format, though, hard to write for people not familiar with it.
- Go struct with YAML tags + comments.
We could discuss the specification itself as well as any other possible use-cases, that should be taken into account during the development.
I have a partially-completed example in this branch for neofs-node: https://github.com/fyrchik/neofs-node/tree/config-gen
It has 2 parts:
- Autogenerate a JSON schema approximation, to speed up adoption. Basically, instead of writing it from scratch, we can take already existing example and have some starting point automatically.
- Autogenerate anything with Go templates (in the branch, I have a template for MD config description).