Skip to content

Config documentation autogeneration #14

Open
@fyrchik

Description

@fyrchik

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    configConfiguration format update or breaking change

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions