Generate Protobuf Doc

[dmdashenkov]

Protobuf documentation doesn't have a conventional format. The comments from .proto files are often dumped into the target languages "as-is". This leads to generated doc (such as Javadoc, DartDoc, etc.) not being very pretty.

We should build a tool for documentation generation for Protobuf on top of ProtoData.

[alexander-yevsyukov]

protoc-gen-doc (pseudomuto) is the long-standing default and what most people mean by "the industry standard." It's a protoc plugin that generates HTML, JSON, DocBook, and Markdown documentation from comments in your .proto files. It's distributed as a binary and a Docker image, and it's template-driven so you can supply your own Go HTML template. The main limitation worth knowing: historically it has focused on messages/enums/fields and its gRPC service rendering is more limited. It's the safe, boring, widely-adopted choice.

https://github.com/pseudomuto/protoc-gen-doc

[alexander-yevsyukov]

Buf / the Buf Schema Registry (BSR) is the modern center of gravity for the whole Protobuf ecosystem. The BSR generates documentation for each module, presenting your .proto files in an organized UI with navigation between them, and lets publishers add module and package information for extra context. It also does schema diffing between commits. The tradeoff: this is a hosted product, not a static-site generator you run locally. If you're already using buf for linting/breaking-change detection (which is increasingly the default in modern Protobuf shops), getting docs is nearly free.

https://buf.build/docs/bsr/documentation/

[alexander-yevsyukov]

sabledocs is a newer static-site generator that exists specifically because of protoc-gen-doc's gaps. The author built it because protoc-gen-doc only works for data contracts and not gRPC, grpc-docs needed React to serve rather than generating static HTML, and GenDocu and Buf are commercial hosted products rather than static content generators. It's a Python (3.11+) package that takes the binary descriptor generated with protoc *.proto -o descriptor.pb --include_source_info as input and produces a static HTML site, with a built-in Lunr search index. Good pick if you want self-hosted static HTML that also documents gRPC services.

https://github.com/markvincze/sabledocs

[alexander-yevsyukov]

Protobuffet generates Docusaurus-flavored docs (MDX + React components). Notably, it still depends on protoc-gen-doc under the hood — using protoc-gen-doc's JSON output as its input, then layers a nicer site on top. Worth it only if you're already a Docusaurus shop.

https://protobuffet.com/docs/how/usage/