This is a documentation generator plugin for the Google Protocol
Buffers compiler (protoc). The plugin can generate HTML, DocBook
or Markdown documentation from comments in your .proto files.
Package repositories for Ubuntu, openSUSE, Fedora and Arch are available at the Open Build Service. For CentOS 7 there's an x64 RPM in the Releases section (it requires Qt and protobuf packages from the EPEL repository).
Use the standalone ZIP distribution available in the Releases section.
See the build instructions in BUILDING.md.
The plugin is invoked by passing the --doc_out option to the
protoc compiler. The option has the following format:
--doc_out=docbook|html|markdown|<TEMPLATE_FILENAME>,<OUT_FILENAME>:<OUT_DIR>
The format may be one of the built-in ones ( docbook, html or
markdown) or the name of a file containing a custom
Mustache template. For example, to generate HTML
documentation for all .proto files in the proto directory into
doc/index.html, type:
protoc --doc_out=html,index.html:doc proto/*.proto
The plugin executable must be in PATH or specified explicitly
using the --plugin option in order for protoc to find it. If
you need support for a custom output format, see the built-in
templates in templates for how to write your
own. 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.
Use /** */ or /// comments to document your files. Comments
for enumerations and messages go before the message/enumeration
definition. Comments for fields or enum values can go either
before or after the field/value definition. If a documentation
comment begins with @exclude, the message, enum, enum value or
field will be excluded from the generated documentation.
With the input .proto files
the plugin gives the output
- Markdown
- HTML
- DocBook
- PDF (Using Apache FOP)
Look in examples/Makefile to see how these outputs were built.