// the find
pseudomuto/protoc-gen-doc
Documentation generator plugin for Google Protocol Buffers
protoc-gen-doc is a plugin for protoc that generates HTML, JSON, DocBook, or Markdown documentation from comments in .proto files. It is for teams that already document their APIs in protobuf comments and want the output in a readable form without writing a generator.
- Custom output uses Go text/template files, so a team can produce any format from the same data model. The repo ships example templates for AsciiDoc and gRPC Markdown.
- The examples directory commits the generated output for every built-in format next to the protos that produced it, so output regressions show up in diffs.
- Proto2 and proto3 files can be processed in the same run, and `@exclude` lets a single element's comment be hidden without touching the rest of the file.
- Distribution is practical: a Docker image, release binaries, and a Maven Central package with a Gradle example mean CI can run it without a Go toolchain.
- The template data model is the real public API, and the custom template docs live on an external wiki rather than in the repo. A template written against one version can break silently when the struct fields change.
- The `--doc_opt` syntax packs the format, output path, exclusion patterns, and extra options into one comma and colon delimited string. The third segment needs a double colon, and it is easy to get wrong without reading the README closely.
- Exclusion is path-glob only, with no per-package or per-message rules. Large monorepos with mixed vendored and first-party protos have to maintain the glob list by hand.
- The HTML output's look is controlled by a stylesheet.css file dropped next to the output, not by a documented theme option. Restyling means overriding the whole page by convention, and the default template has no configuration hooks.