Config documentation autogeneration #14

New Issue

Open

opened 2023-02-16 10:59:06 +00:00 by fyrchik · 1 comment

fyrchik commented

2023-02-16 10:59:06 +00:00

(Migrated from github.com)

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).

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).