Documentation generator plugin for Google Protocol Buffers
Clone or download
pseudomuto Merge pull request #372 from htdvisser/feature/streaming-rpcs
Add "streaming" indicator to requests/responses of streaming RPCs
Latest commit c35c052 Aug 27, 2018
Permalink
Failed to load latest commit information.
cmd/protoc-gen-doc Move a few things and add some badges Feb 23, 2018
examples Add streaming RPC to examples Aug 27, 2018
fixtures Simplify fixtures Feb 23, 2018
resources Add "stream" behind request/response types of streaming RPCs in templ… Aug 27, 2018
script Add -Iprotos to entrypoint to keep file names the same Feb 23, 2018
.dockerignore Make a docker image for running protoc-gen-doc Aug 6, 2017
.gitignore Move a few things and add some badges Feb 23, 2018
.gofmtignore Move a few things and add some badges Feb 23, 2018
.travis.yml Bump protobuf to 3.6.1 to support newer features Aug 13, 2018
CHANGELOG.md Update CHANGELOG Aug 27, 2018
CONTRIBUTING.md dep init, retool, protoc 3.5.1, and go 1.10 Feb 22, 2018
Dockerfile Bump protobuf to 3.6.1 to support newer features Aug 13, 2018
Gopkg.lock Bump protobuf to 3.6.1 to support newer features Aug 13, 2018
Gopkg.toml Bump protobuf to 3.6.1 to support newer features Aug 13, 2018
LICENSE.md Clean slate Aug 6, 2017
Makefile Use String() for comparing Regexp objects Jun 2, 2018
README.md Update go get package [ci skip] Feb 23, 2018
bench_test.go Simplify fixtures Feb 23, 2018
doc.go Support exclude file patterns Nov 14, 2017
filters.go Remove some unused code Nov 11, 2017
filters_test.go nobr: preserve blank lines Oct 2, 2017
plugin.go Ensure ExcludePatterns is still an option Feb 23, 2018
plugin_test.go Use String() for comparing Regexp objects Jun 2, 2018
renderer.go Add unit tests May 31, 2018
renderer_test.go Simplify fixtures Feb 23, 2018
resources.go Add "stream" behind request/response types of streaming RPCs in templ… Aug 27, 2018
template.go Add stream indicator to requests and responses of streaming RPCs Aug 27, 2018
template_test.go Add stream indicator to requests and responses of streaming RPCs Aug 27, 2018
tools.json Move a few things and add some badges Feb 23, 2018
version.go Bump version to 1.1.0 Mar 13, 2018

README.md

protoc-gen-doc

Travis Build Status codecov GoDoc Go Report Card

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 pseudomuto/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 get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc

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>

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.

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 \
  pseudomuto/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 \
  pseudomuto/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 \
  pseudomuto/protoc-gen-doc --doc_opt=markdown,docs.md /protos/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 delimited by :. For example, you can pass any number of comma separated patterns as the second option:

docker run --rm \
  -v $(pwd)/examples/doc:/out \
  -v $(pwd)/examples/proto:/protos \
  pseudomuto/protoc-gen-doc --doc_opt=: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

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

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 simply prefix the comment with @exclude.

Example: include only the comment for the id field

/**
 * @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 the value of this message. */
  int32 value = 3;
}

Check out the example protos to see all the options.

Output Example

With the input .proto files

the plugin gives the output

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