[WIP] docs: script for generating config docs

[lookharm]

This pr introduces an initial solution to extract comments associated with a Config struct and then generate the config docs. The current implementation only supports single-level structs; nested structs are not supported yet. It will solve issue #4274. If this initial approach is accepted, I plan to make it complete.

A few questions to make it clearer:

• Where will be this script placed? Should it be in docs/generate.go?

(cc @jedevc)

[jedevc]

Heya @lookharm 👋 Thanks so much for giving this a go - nice work so far! 🎉

The only thing that you don't have there that I think would be really nice would be a way of printing out values from the target Config{} struct. With that, we could put down the existing sample configuration into code, and then print it all out with the comments 🎉

BTW - if you don't mind me asking, how did you come across the issue? I genuinely wasn't expecting anyone to pick it up so soon, so thanks!

Where will be this script placed? Should it be in docs/generate.go?

The logic in docs/generate.go is quite generic at the moment - it just replaces the contents of a <!---GENERATE_START <cmd>--> block with the output of running that <cmd> (see #3747 for where it was initially added). Ideally, we wouldn't need to update that, we'd just need to write our own little tool that prints out the config structure and some helpful messages for it.

I'm not sure where the little tool to do this would be though - for now, feel free to put it anywhere (like under docs/generate/config/config.go) - we can change it later.

Then we'd just do something like this in config.md:

This is the format of the config file:

<!---GENERATE_START go run ./generate/config/config.go-->
<!---GENERATE_END-->

[lookharm]

Thanks for the response. After thinking about this.

I think it would be really nice would be a way of printing out values from the target Config{} struct.

According to go-tomal documentation https://pkg.go.dev/github.com/pelletier/go-toml@v1.9.5#Marshal. Don't you think this should be done with the TOML marshaler? For example,

type Config struct {
  Debug true `toml: "debug", comment: "Debug is bool"`
}

func main() {
  out, _ := toml.Marshal(Config{Debug: true})
  fmt.Println(string(out))
}

The output is:

# Debug is bool
debug = true

This way, it is easier and doesn't require any TOML parsing that go-toml package has done.

BTW - if you don't mind me asking, how did you come across the issue? I genuinely wasn't expecting anyone to pick it up so soon, so thanks!

I often use Docker and just want to learn more about how the internal works, I hope the contributions will help me, and I think the buildkit is a good starting point. If any issues that you see are good for the starter, please tell me.

[jedevc]

Ahhh the TOML marshaller would be nice - but, I don't really like the pattern of reading the comments from a separate field. It means everything has to be in a sine line, which is not very easy to read or edit.

If we could keep the comments as go-style doc comments, I think using the TOML marshaller would be perfect! That said, I'd be happy to be persuaded if there's really no easy way to do this in code.

[jedevc]

@lookharm just wanted to check-in - are you blocked on this, anything you need help with from our end? No rush, I've just been thinking about improving the config docs as well, and this was on-theme with that.

[jsternberg]

I'm closing this because the PR is in draft and seems to have stalled. If this is something you're still interested in picking up, please open a new PR when it is ready to be reviewed. Thanks.