Skip to content

Config documentation autogeneration #14

Open
fyrchik opened this issue Feb 16, 2023 · 0 comments
Open

Config documentation autogeneration #14

fyrchik opened this issue Feb 16, 2023 · 0 comments
Labels
config Configuration format update or breaking change

Comments

@fyrchik
Copy link

fyrchik commented Feb 16, 2023

We have multiple things which are in theory derivable from a single source of truth:

  1. Config example.
  2. Config documentation in any format.
  3. 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:

  1. JSON schema. Well-known format, though, hard to write for people not familiar with it.
  2. 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:

  1. 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.
  2. Autogenerate anything with Go templates (in the branch, I have a template for MD config description).
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
config Configuration format update or breaking change
Projects
None yet
Development

No branches or pull requests

1 participant