Config documentation autogeneration #96

New issue

Closed

opened 2025-12-28 17:36:08 +00:00 by sami · 1 comment

sami commented

2025-12-28 17:36:08 +00:00

Owner

Originally created by @fyrchik on GitHub (Feb 16, 2023).

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

Originally created by @fyrchik on GitHub (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).