Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Auto-generate config docs from code #4274

Open
jedevc opened this issue Sep 25, 2023 · 2 comments · May be fixed by #4292
Open

Auto-generate config docs from code #4274

jedevc opened this issue Sep 25, 2023 · 2 comments · May be fixed by #4292
Labels
exp/beginner help wanted kind/docs

Comments

@jedevc
Copy link
Member

jedevc commented Sep 25, 2023

The definition for the buildkit.toml format lives in https://github.com/moby/buildkit/blob/0f6482e34cec2d25c4397b812e442e1c8eea06d0/cmd/buildkitd/config/config.go

The fields are all documented in https://github.com/moby/buildkit/blob/0f6482e34cec2d25c4397b812e442e1c8eea06d0/docs/buildkitd.toml.md.

However, these can be out-of-date, which means sometimes we get drift - see #4273, which should have been updated as part of #3773, but got missed.

Ideally, we should auto-generate part of the buildkit docs using the code, by extracting doc-comments, and analyzing the types.

(cc @dvdksn)
@jedevc jedevc mentioned this issue Sep 25, 2023
Merged
@dvdksn
Copy link
Collaborator

dvdksn commented Sep 26, 2023

Would generating this involve parsing the AST to get the fields and comments, or do you have a better idea/tool in mind?

@jedevc
Copy link
Member Author

jedevc commented Sep 27, 2023

Would generating this involve parsing the AST to get the fields and comments, or do you have a better idea/tool in

We could potentially use https://pkg.go.dev/go/parser, and then use https://pkg.go.dev/go/doc to extract doc comments.

I'm not aware of any off-the-shelf tool for this, but shouldn't be too tricky to throw something together.

@lookharm lookharm linked a pull request Sep 29, 2023 that will close this issue
Draft
@jedevc jedevc linked a pull request Sep 30, 2023 that will close this issue
[WIP] docs: script for generating config docs #4292
Draft
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
exp/beginner help wanted kind/docs
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

[WIP] docs: script for generating config docs lookharm/buildkit
3 participants
@tonistiigi @jedevc @dvdksn