protoc-gen-doc
github.com
- Free plan
- Windows
- macOS
- Linux
- Self-hosted
What protoc-gen-doc is
protoc-gen-doc creates reference documentation from comments in Google Protocol Buffers files. It runs as a plugin through protoc, using the --doc_out and --doc_opt options, and can produce HTML, JSON, DocBook, or Markdown. It handles proto2 and proto3, including projects that use both. Comments can describe files, messages, fields, services, methods, enums, enum values, and extensions. Teams can omit files using path patterns or leave out comments prefixed with @exclude. A custom Go template can define the output format, and a stylesheet.css file can change the appearance of HTML output. The source_relative flag places generated files in the same relative directory as their input. Installation choices include Go, prebuilt releases, Docker, and Maven Central. The software is free and open source under the MIT License, which permits use, modification, and distribution under its terms. It can be self-hosted on Linux, macOS, or Windows.
Who it suits
It suits developers maintaining proto2 or proto3 definitions who want documentation generated from comments in their files. Teams can adapt the output with templates or CSS and run the tool in their own environment.
Good to know, and what to watch
- Generates HTML, JSON, DocBook, and Markdown.
- Supports proto2 and proto3 in the same context.
- Documents files, messages, fields, services, and more.
- Offers Go templates and CSS customization.
- Available through Go, Docker, releases, and Maven Central.
- The MIT License provides the software without warranty.
- The repository has no SECURITY.md policy or published advisories.
Plans
Every plan and priceMIT-licensed software
Open source
Getting started
- Open https://github.com/pseudomuto/protoc-gen-doc
- Install with Go, a prebuilt release, Docker, or Maven Central
- Prepare .proto files with documentation comments
- Invoke protoc with --doc_out and --doc_opt
- Choose an output format or provide a custom Go template
- Use source_relative, exclusion patterns, or @exclude as needed
The Club's review
protoc-gen-doc is a Protocol Buffers documentation generator for teams that maintain .proto files and want their comments to serve as reference material. It is best for developers who already build with protoc and can manage a self-hosted tool. Its format and template options are useful, but it remains a focused generator rather than a broader gRPC workbench.
Overview
The plugin turns comments in .proto files into HTML, JSON, DocBook, or Markdown. It supports proto2 and proto3, including projects that use both, and can document files, messages, fields, services, methods, enums, enum values, and extensions. That broad coverage makes it useful for keeping reference documentation close to the definitions it describes.
It runs through protoc with the --doc_out and --doc_opt options. The source_relative flag places generated output in the same relative directory as the input, which can help keep documentation aligned with a source tree. This workflow assumes familiarity with Protocol Buffers and compiler plugins; readers seeking a graphical tool for calling or testing services should look elsewhere.
Key features
Four built-in formats serve different publishing needs: HTML for browser-readable references, JSON for structured output, DocBook for document workflows, and Markdown for text-based publishing. A custom Go template can produce a different format, and a stylesheet.css file beside the output can style generated HTML. The flexibility is useful when defaults do not fit a project, though custom templates and styles add work to maintain.
Filtering can exclude files using path patterns or omit comments marked with @exclude. This gives maintainers control over what appears in generated references, including a way to keep selected comments out of the output.
Installation choices include Go, prebuilt releases, a Docker image, and a Maven Central package. The Docker image uses /out and /protos volumes for generated documents and input files, fitting projects that want a container-based workflow. The v1.0.0 release notes describe precompiled Linux, OSX, and Windows builds; the project also lists Linux, macOS, Windows, and self-hosted support.
Pricing
protoc-gen-doc is open-source software under the MIT License. The MIT-licensed software plan costs free and permits use, copying, modification, merging, publishing, distribution, sublicensing, and sale under its terms. There are no paid tiers or seat limits described. The license provides the software “AS IS” without warranty, so users take responsibility for their own deployment and maintenance.
Platforms
The project supports Linux, macOS, and Windows, and is self-hosted. That suits development teams that can run a compiler plugin in their own build environment; it does not describe a hosted documentation service.
Who it's for
This is a good fit for teams that maintain Protocol Buffers schemas and want generated references in a format their existing publishing workflow can use. It is especially practical when comments are already maintained in .proto files and output needs to follow the source directory structure. Teams that need a visual gRPC client, load testing, or a hosted workspace should consider tools built for those jobs instead.
Pros and cons
Pros
- HTML, JSON, DocBook, and Markdown output lets teams reuse schema comments across different documentation workflows.
- Support for proto2 and proto3, including both in one context, accommodates mixed-syntax projects.
- Custom Go templates, CSS styling, and filtering give maintainers control over format, appearance, and scope.
- Go, release, Docker, and Maven installation routes provide several ways to integrate the plugin into a build setup.
Cons
- The tool is self-hosted and invoked through protoc, so it suits build workflows rather than users seeking a standalone hosted editor.
- Custom templates and CSS can require ongoing maintenance when a project changes its documentation needs.
- The MIT license provides no warranty, and the repository has no SECURITY.md policy or published security advisories.
Alternatives
For a broader directory of related tools, see gRPC Tools.
Choose Kreya if you want a cross-platform gRPC client with a free individual plan and request history limited to the latest request; it is freemium and not open source. Sabledocs is another free, open-source static documentation generator for Linux, macOS, and Windows, but it requires Python 3.11 or later and a Protobuf descriptor file.
FintX is a better fit for working with gRPC clients and requests: its free open-source plan includes unlimited clients, saved requests, import and export, tabs per method, a JSON editor, and projects. For load testing, ghz offers a free open-source CLI and Go package, with a complementary web application in beta.
grpcmd suits users who want to send requests, start a server, use reflection, list and describe methods, or script with JavaScript; those features are in its free annual plan. gRPC CLI is a free option for building from source and making unary RPC calls. For Go-focused gRPC testing utilities, consider grpcmock-go. ProtoCall offers a free app with GitHub imports and manually created workspaces.
Verdict
Choose protoc-gen-doc if your team maintains .proto comments and wants configurable reference output integrated with protoc, especially when a free, self-hosted MIT-licensed tool fits your build environment. Its strongest reason to choose it is the combination of four output formats, schema coverage, and template and filtering controls. Look elsewhere if you need interactive gRPC operations, load testing, or a hosted workspace rather than generated documentation.
The verdict
protoc-gen-doc turns Protocol Buffers comments into documentation in several formats, with options to control content, layout, and output location. It is free to use under the MIT License, which provides no warranty.
Questions people ask
Is protoc-gen-doc free?
Yes. It is free and open source under the MIT License.
Which operating systems does it support?
It runs on Linux, macOS, and Windows, and supports self-hosted deployment.
What output formats can it generate?
It generates HTML, JSON, DocBook, and Markdown documentation from .proto comments.
How is protoc-gen-doc installed?
The project documents installation through Go, prebuilt releases, a Docker image, and Maven Central.
Can generated documentation be customized?
Yes. You can provide a custom Go template and style HTML with a stylesheet.css file beside the output.
What license does it use?
It uses the MIT License, which permits use, copying, modification, distribution, sublicensing, and sale under its terms.
What the maker publishes
- Comment filtering
- Comments prefixed with @exclude can be omitted from generated documentation. source
- Customization
- Users can supply a custom Go template and can customize HTML output with a stylesheet.css file. source
- Custom templates
- The output format can be a custom Go template, and CSS placed beside the output file can customize HTML appearance. source
- Deployment
- The README describes a Docker image with /out and /protos volumes for documentation output and proto inputs. source
- Documentable elements
- Comments can document files, messages, fields, services and methods, enums and values, and extensions. source
- Documentable elements
- Comments can document files, messages, fields, services and methods, enums and values, and extensions. source
- Filtering
- The plugin supports excluding files by path patterns and excluding comments with the @exclude prefix. source
- Installation
- The project offers a Docker image, Go installation, prebuilt releases, and a Maven Central package. source
- Install options
- The README documents installation with Go, prebuilt releases, a Docker image, and Maven Central. source
- Integration
- The plugin is invoked through protoc using the --doc_out and --doc_opt options. source
- License
- The software is distributed under the MIT License, which permits use, copying, modification, distribution, sublicensing, and sale subject to its terms. source
- License and warranty
- The project uses the MIT License, which provides the software “AS IS” without warranty. source
- Maintainer
- The GitHub profile identifies the maintainer as David Muto and lists Ottawa, Ontario, Canada. source
- Output formats
- It generates HTML, JSON, DocBook, and Markdown documentation from comments in .proto files. source
- Output formats
- It can generate HTML, JSON, DocBook, and Markdown documentation from comments in .proto files. source
- Output path option
- The source_relative flag writes generated output in the same relative directory as the input file. source
- Proto support
- It supports proto2 and proto3, including both in the same context. source
- Proto support
- It supports proto2 and proto3, including both in the same context. source
- Purpose
- protoc-gen-doc is a documentation generator plugin for the Google Protocol Buffers compiler. source
- Purpose
- protoc-gen-doc is a documentation generator plugin for the Google Protocol Buffers compiler. source
- Release
- The releases page lists v1.5.1 as the latest release and shows its tag as signed with a verified committer signature. source
- Release platforms
- The v1.0.0 release notes say the program was ported to Go and precompiled for Linux, OSX, and Windows. source
- Release signature
- The v1.5.1 release page says its tag was signed with the committer’s verified signature. source
- Security
- The repository says it has no SECURITY.md security policy and no published security advisories. source
Checked against the maker's pages on 8 Oct 2026.