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).
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
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.
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 forprotos/*.proto
, which can be changed by mounting different volumes.
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.
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
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.
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.
With the input .proto
files
the plugin gives the output
Check out the examples
task in the Makefile to see how these were generated.