Generate Protobuf documentation?

Question

Does anyone know of a good tool to generate Google Protobuf documentation using the .proto source files?

Answer 1

[Update: Aug 2017. Adapted to the full Go rewrite of protoc-gen-bug, currently 1.0.0-rc]

The protoc-doc-gen, created by @estan (see also his earlier answer) provides a good and easy way to generate your documentation in html, json, markdown, pdf and other formats.

There are number of additional things that I should mention:

1. estan is no longer the maintainer of protoc-doc-gen, but pseudomuto is
2. In contrast to what I've read on various pages it is possible to use rich inline formatting (bold/italic, links, code snippets, etc.) within comments
3. protoc-gen-doc has been completely rewritten in Go and now uses Docker for generation (instead of apt-get)

The repository is now here: https://github.com/pseudomuto/protoc-gen-doc

To demonstrate the second point I have created an example repository to auto-generate the Dat Project Hypercore Protocol documentation in a nice format.

You can view various html and markdown output generation options at (or look here for a markdown example on SO):

• https://github.com/aschrijver/protoc-gen-doc-example

The TravisCI script that does all the automation is this simple .travis.yml file:

sudo: required

services:
  - docker

language: bash

before_script:
  # Create directory structure, copy files
  - mkdir build && mkdir build/html
  - cp docgen/stylesheet.css build/html

script:
  # Create all flavours of output formats to test (see README)
  - docker run --rm -v $(pwd)/build:/out -v $(pwd)/schemas/html:/protos:ro pseudomuto/protoc-gen-doc
  - docker run --rm -v $(pwd)/build/html:/out -v $(pwd)/schemas/html:/protos:ro -v $(pwd)/docgen:/templates:ro pseudomuto/protoc-gen-doc --doc_opt=/templates/custom-html.tmpl,inline-html-comments.html protos/HypercoreSpecV1_html.proto
  - docker run --rm -v $(pwd)/build:/out -v $(pwd)/schemas/md:/protos:ro pseudomuto/protoc-gen-doc --doc_opt=markdown,hypercore-protocol.md
  - docker run --rm -v $(pwd)/build:/out -v $(pwd)/schemas/md:/protos:ro -v $(pwd)/docgen:/templates:ro pseudomuto/protoc-gen-doc --doc_opt=/templates/custom-markdown.tmpl,hypercore-protocol_custom-template.md protos/HypercoreSpecV1_md.proto

deploy:
  provider: pages
  skip_cleanup: true          # Do not forget, or the whole gh-pages branch is cleaned
  name: datproject            # Name of the committer in gh-pages branch
  local_dir: build            # Take files from the 'build' output directory
  github_token: $GITHUB_TOKEN # Set in travis-ci.org dashboard (see README)
  on:
    all_branches: true        # Could be set to 'branch: master' in production

(PS: The hypercore protocol is one of the core specifications of the Dat Project ecosystem of modules for creating decentralized peer-to-peer applications. I used their .proto file to demonstrate concepts)

Answer 2

An open source protobuf plugin that generates DocBook and PDF from the proto files.

http://code.google.com/p/protoc-gen-docbook/

Disclaimer: I am the author of the plugin.

Answer 3

In addition to the askldjd's answer, I'd like to point out my own tool at https://github.com/estan/protoc-gen-doc . It is also a protocol buffer compiler plugin, but can generate HTML, MarkDown or DocBook out of the box. It can also be customized using Mustache templates to generate any text based format you like.

Documentation comments are written using /** ... */ or /// ....

Answer 4

In Protobuf 2.5 the "//" comments you put into your .proto files actually makes it into the generated java source code as Javadoc comments. More specifically the protoc compiler will take your "//" comments like this:

// 
// Message level comments
message myMsg {

    // Field level comments
    required string name=1;
}

will go into your generated java source files. For some reason protoc encloses the Javadoc comments in <pre> tags. But all in all it is a nice new feature in v2.5.

Answer 5

The thread is old, but the question still seems relevant. I have had very good results with doxygen + proto2cpp. proto2cpp works as an input filter for doxygen.

Answer 6

Doxygen supports so called input filters, which allow you to transform code into something doxygen understands. Writing such a filter for transforming the Protobuf IDL into C++ code (for example) would allow you to use the full power of Doxygen in .proto files. See item 12 of the Doxygen FAQ.

I did something similar for CMake, the input filter just transforms CMake macros and functions to C function declarations. You can find it here.

Answer 7

Since the .proto file is mostly just declaration, I usually find that the source file with inline comments is straightforward and effective documentation.

Answer 8

https://code.google.com/apis/protocolbuffers/docs/techniques.html

Self-describing Messages

Protocol Buffers do not contain descriptions of their own types. Thus, given only a raw message without the corresponding .proto file defining its type, it is difficult to extract any useful data.

However, note that the contents of a .proto file can itself be represented using protocol buffers. The file src/google/protobuf/descriptor.proto in the source code package defines the message types involved. protoc can output a FileDescriptorSet – which represents a set of .proto files – using the --descriptor_set_out option. With this, you could define a self-describing protocol message like so:

message SelfDescribingMessage { // Set of .proto files which define the type. required FileDescriptorSet proto_files = 1;

// Name of the message type. Must be defined by one of the files in // proto_files. required string type_name = 2;

// The message data. required bytes message_data = 3; }

By using classes like DynamicMessage (available in C++ and Java), you can then write tools which can manipulate SelfDescribingMessages.

All that said, the reason that this functionality is not included in the Protocol Buffer library is because we have never had a use for it inside Google.