Skip to the content
Know your tech before you buy it. Makers: get listed from $49/mo

protoc-gen-doc

github.com

  • Free plan
  • Windows
  • macOS
  • Linux
  • Self-hosted
7.7 Club score Visit github.com

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.

MIT-licensed software

Free

Open source

Getting started

  1. Open https://github.com/pseudomuto/protoc-gen-doc
  2. Install with Go, a prebuilt release, Docker, or Maven Central
  3. Prepare .proto files with documentation comments
  4. Invoke protoc with --doc_out and --doc_opt
  5. Choose an output format or provide a custom Go template
  6. 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.