lima-vm / lima-vm/lima

Auto-generate gRPC API reference with protoc-gen-doc

Open
#5,224 0 comments 0 reactions 0 assignees View on GitHub
area/vmdrivers documentation question
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.