protoc-gen-doc

This is a documentation generator plugin for the Google Protocol Buffers compiler (protoc). The plugin can generate HTML, JSON, DocBook, and Markdown documentation from comments in your .proto files.

It supports proto2 and proto3, and can handle having both in the same context (see examples for proof).

Installation

There is a Docker image available (docker pull daotl/protoc-gen-doc) that has everything you need to generate documentation from your protos.

If you'd like to install this locally, you can go get it.

go install github.com/daotl/protoc-gen-doc/cmd/protoc-gen-doc@latest

Alternatively, you can download a pre-built release for your platform from the releases page.

Finally, this plugin is also available on Maven Central. For details about how to use it, check out the gradle example.

Invoking the Plugin

The plugin is invoked by passing the --doc_out, and --doc_opt options to the protoc compiler. The option has the following format:

--doc_opt=<FORMAT>|<TEMPLATE_FILENAME>,<OUT_FILENAME>[,default|source_relative][:<OPTION>[,<OPTION>...]]

The format may be one of the built-in ones ( docbook, html, markdown or json) or the name of a file containing a custom Go template.

If the source_relative flag is specified, the output file is written in the same relative directory as the input file.

Using the Docker Image (Recommended)

The docker image has two volumes: /out and /protos which are the directory to write the documentation to and the directory containing your proto files.

You could generate HTML docs for the examples by running the following:

docker run --rm \
  -v $(pwd)/examples/doc:/out \
  -v $(pwd)/examples/proto:/protos \
  daotl/protoc-gen-doc

By default HTML documentation is generated in /out/index.html for all .proto files in the /protos volume. This can be changed by passing the --doc_opt parameter to the container.

For example, to generate Markdown for all the examples:

docker run --rm \
  -v $(pwd)/examples/doc:/out \
  -v $(pwd)/examples/proto:/protos \
  daotl/protoc-gen-doc --doc_opt=markdown,docs.md

You can also generate documentation for a single file. This can be done by passing the file(s) to the command:

docker run --rm \
  -v $(pwd)/examples/doc:/out \
  -v $(pwd)/examples/proto:/protos \
  daotl/protoc-gen-doc --doc_opt=markdown,docs.md Booking.proto [OPTIONALLY LIST MORE FILES]

You can also exclude proto files that match specific path expressions. This is done by passing a second option segment delimited by :. For example, you can pass any number of comma separated patterns with exclude_patterns:

docker run --rm \
  -v $(pwd)/examples/doc:/out \
  -v $(pwd)/examples/proto:/protos \
  daotl/protoc-gen-doc --doc_opt=:exclude_patterns=google/*,somepath/*

Remember: Paths should be from within the container, not the host!

NOTE: Due to the way wildcard expansion works with docker you cannot use a wildcard path (e.g. protos/*.proto) in the file list. To get around this, if no files are passed, the container will generate docs for protos/*.proto, which can be changed by mounting different volumes.

Simple Usage

For example, to generate HTML documentation for all .proto files in the proto directory into doc/index.html, type:

protoc --doc_out=./doc --doc_opt=html,index.html proto/*.proto

Excluding Files

You can exclude proto files that match specific path expressions by passing a second option delimited by : with comma-separated exclude_patterns:

protoc --doc_out=./doc --doc_opt=html,index.html:exclude_patterns=google/*,third_party/* proto/*.proto

The plugin executable must be in PATH for this to work.

Using a precompiled binary

Alternatively, you can specify a pre-built/not in PATH binary using the --plugin option.

protoc \
  --plugin=protoc-gen-doc=./protoc-gen-doc \
  --doc_out=./doc \
  --doc_opt=html,index.html \
  proto/*.proto

With a Custom Template

If you'd like to use your own template, simply use the path to the template file rather than the type.

protoc --doc_out=./doc --doc_opt=/path/to/template.tmpl,index.txt proto/*.proto

Additional Options

You can pass additional options in the second segment after ::

protoc --doc_out=./doc --doc_opt=html,index.html:exclude_patterns=google/*,camel_case_fields=true proto/*.proto

Supported options in the second segment:

• exclude_patterns=...: one or more comma-separated patterns to exclude.
• camel_case_fields=true|false: emit field names in lowerCamelCase (default false).
• exclude_directive=...: customize the paragraph/block exclusion directive (default @exclude). Can be repeated to specify multiple directives.
• exclude_line_directive=...: customize the line-level exclusion directive (default @exclude-line). Can be repeated to specify multiple directives.

Customizing Exclusion Directives

By default, the plugin recognizes @exclude for paragraph/block exclusion and @exclude-line for line-level exclusion. You can customize these directives or add additional ones using the options:

# Use different directives
protoc --doc_out=./doc \
  --doc_opt=html,index.html:exclude_directive=skip,exclude_line_directive=skip-line \
  proto/*.proto

# Add multiple directives (e.g., ignore buf lint comments)
protoc --doc_out=./doc \
  --doc_opt=html,index.html:exclude_line_directive=@exclude-line,exclude_line_directive=buf:lint:ignore \
  proto/*.proto

This allows you to integrate with other tools' comment directives. For example, you can configure the plugin to ignore comments from linters like buf:lint:ignore, skipcq, nolint, etc.

For information about the available template arguments and functions, see Custom Templates. If you just want to customize the look of the HTML output, put your CSS in stylesheet.css next to the output file and it will be picked up.

Writing Documentation

Messages, Fields, Services (and their methods), Enums (and their values), Extensions, and Files can be documented. Generally speaking, comments come in 2 forms: leading and trailing.

Leading comments

Leading comments can be used everywhere.

/**
 * This is a leading comment for a message
 */
message SomeMessage {
  // this is another leading comment
  string value = 1;
}

NOTE: File level comments should be leading comments on the syntax directive.

Trailing comments

Fields, Service Methods, Enum Values and Extensions support trailing comments.

enum MyEnum {
  DEFAULT = 0; // the default value
  OTHER   = 1; // the other value
}

Excluding comments

If you want to have some comment in your proto files, but don't want them to be part of the docs, you can use the @exclude and @exclude-line directives. These directives are customizable via the exclude_directive and exclude_line_directive options (see Additional Options for details).

@exclude - Exclude entire paragraphs

The @exclude directive excludes entire paragraphs when it appears at the start of a paragraph (blank lines separate paragraphs):

/**
 * @exclude
 * This comment won't be rendered
 */
message ExcludedMessage {
  string id   = 1; // the id of this message.
  string name = 2; // @exclude the name of this message

  // @exclude this entire paragraph
  // some more comments
  int32 value = 3;

  /* @exclude this block too */
  int32 value2 = 4;
}

@exclude-line - Exclude single lines

The @exclude-line directive excludes only the line it appears on (when it's at the beginning of the line), while keeping other lines in the same paragraph:

// Keep this line
// @exclude-line excludes this line
// Keep this line also
int32 value1 = 5;

Output: Keep this line\nKeep this line also

Note: @exclude-line only works when it appears at the beginning of a line (after trimming whitespace). If it appears elsewhere in the line, the line will not be excluded:

// Keep this line
// @exclude won't exclude this line
// @exclude-line excludes this line
// non-leading @exclude-line won't exclude this line
// Keep this line also
int32 value2 = 6;

Output: Keep this line\n@exclude won't exclude this line\nnon-leading @exclude-line won't exclude this line\nKeep this line also

Multi-paragraph comments

Comments are grouped into paragraphs separated by blank lines or block comments containing @exclude. All non-excluded parts are preserved in their original paragraph structure:

/* Keep this comment */
// @exclude middle paragraph
/* Keep this comment also */
int32 value = 6;

Output: Keep this comment\n\nKeep this comment also

// Keep this comment
/* @exclude middle paragraph */
// Keep this comment also
int32 value = 7;

Output: Keep this comment\n\nKeep this comment also

Check out the example protos to see all the options.

Output Example

With the input .proto files

• Booking.proto
• Customer.proto
• Vehicle.proto

the plugin gives the output

• Markdown
• HTML
• DocBook
• JSON

Check out the examples task in the Makefile to see how these were generated.