- Home
- gRPC Tools
- protoc-gen-doc
protoc-gen-doc
What it is
protoc-gen-doc creates reference documentation from comments in Protocol Buffers .proto files. Used as a plugin with protoc through the --doc_out and --doc_opt options, it supports proto2 and proto3, including files that use both. Output can be generated as HTML, JSON, DocBook, or Markdown, with comments describing files, messages, fields, services, methods, enums, values, and extensions. Path patterns can exclude files, and comments marked with the @exclude prefix can be left out. For customization, users can provide a Go template; a stylesheet.css file beside the output can change HTML styling. The source_relative option puts generated files in the same relative directory as their inputs. Installation options include Go, prebuilt releases, a Docker image, and a Maven Central package. It runs on Linux, macOS, and Windows and is self-hosted. The software is free under the MIT License, which permits use and modification under its terms and provides it without warranty. The repository lists no security policy or published advisories.
For and against
For
- Generates HTML, JSON, DocBook, and Markdown.
- Supports proto2 and proto3 together.
- Custom Go templates and CSS allow output changes.
- Offers Go, Docker, prebuilt, and Maven installation paths.
Against
- Self-hosted deployment is required.
- The MIT License provides the software without warranty.
- The repository lists no security policy or published advisories.
The verdict
protoc-gen-doc is a focused option for generating reference material from Protocol Buffers comments, with several output formats and filtering controls. Its self-hosted setup and lack of a published security policy are relevant considerations for teams evaluating it.
Who it suits
It suits teams and developers who maintain Protocol Buffers definitions and want documentation generated from their comments. It can also fit projects that need control over output formats, styling, or which files and comments are included.
Plans and prices
MIT-licensed software
Use, copy, modify, merge, publish, distribute, sublicense, and sell under the MIT License · provided “AS IS” without warranty
Read 8 Oct 2026 · github.com
On the record
- Comment filtering
- Comments prefixed with @exclude can be omitted from generated documentation.github.com · read 8 Oct 2026
- Customization
- Users can supply a custom Go template and can customize HTML output with a stylesheet.css file.github.com · read 4 Oct 2026
- Custom templates
- The output format can be a custom Go template, and CSS placed beside the output file can customize HTML appearance.github.com · read 8 Oct 2026
- Deployment
- The README describes a Docker image with /out and /protos volumes for documentation output and proto inputs.github.com · read 8 Oct 2026
- Documentable elements
- Comments can document files, messages, fields, services and methods, enums and values, and extensions.github.com · read 8 Oct 2026
- Filtering
- The plugin supports excluding files by path patterns and excluding comments with the @exclude prefix.github.com · read 4 Oct 2026
- Installation
- The project offers a Docker image, Go installation, prebuilt releases, and a Maven Central package.github.com · read 4 Oct 2026
- Install options
- The README documents installation with Go, prebuilt releases, a Docker image, and Maven Central.github.com · read 8 Oct 2026
- Integration
- The plugin is invoked through protoc using the --doc_out and --doc_opt options.github.com · read 8 Oct 2026
- License
- The software is distributed under the MIT License, which permits use, copying, modification, distribution, sublicensing, and sale subject to its terms.github.com · read 4 Oct 2026
- License and warranty
- The project uses the MIT License, which provides the software “AS IS” without warranty.github.com · read 8 Oct 2026
- Maintainer
- The GitHub profile identifies the maintainer as David Muto and lists Ottawa, Ontario, Canada.github.com · read 8 Oct 2026
- Output formats
- It can generate HTML, JSON, DocBook, and Markdown documentation from comments in .proto files.github.com · read 8 Oct 2026
- Output path option
- The source_relative flag writes generated output in the same relative directory as the input file.github.com · read 4 Oct 2026
- Proto support
- It supports proto2 and proto3, including both in the same context.github.com · read 8 Oct 2026
- Purpose
- protoc-gen-doc is a documentation generator plugin for the Google Protocol Buffers compiler.github.com · read 8 Oct 2026
- Release
- The releases page lists v1.5.1 as the latest release and shows its tag as signed with a verified committer signature.github.com · read 8 Oct 2026
- Release platforms
- The v1.0.0 release notes say the program was ported to Go and precompiled for Linux, OSX, and Windows.github.com · read 8 Oct 2026
