Auto-generate gRPC API reference with protoc-gen-doc
- Dominant language
- Go
- Stars
- 21.9k
- Forks
- 957
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 53
Description
Should Lima adopt [`protoc-gen-doc`](https://github.com/pseudomuto/protoc-gen-doc) to auto-generate a browsable Markdown reference?
For example, for the external driver gRPC API from [driver.proto](https://github.com/limavm/lima/blob/master/pkg/driver/external/driver.proto).
## Context
Follow-up from #4896 and the review of #5221. #5221 keeps the non-controversial part: doc comments added directly to `driver.proto`, which also improve the godoc for the `driver.Driver` interface. Per @AkihiroSuda's suggestion, the `protoc-gen-doc` decision is split out here.
## Pros
- Single source of truth: the reference is derived from the proto comments, so there is no second hand-maintained copy to drift.
- A rendered, searchable page is friendlier to external driver authors than reading the `.proto` or godoc.
## Cons
- godoc already documents the `Driver` interface, so a website page may be redundant.
- The API is small, so a full generated reference is arguably overkill.
- Generated files should not be committed; they belong in `make docsy` at netlify build time (like `limactl.md`).
- Adopting `protoc-gen-doc` adds a build-time tool dependency to `hack/tools`.
Contributor guide
Research direction
Start by reading pkg/driver/external/driver.proto and the existing make docsy flow, including how limactl.md is generated. Evaluate whether protoc-gen-doc should be added through hack/tools and whether its output belongs in the Netlify build; done means a clear adoption decision and, if accepted, a browsable generated reference without committed generated files.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- build-system, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100