Generate Protobuf documentation? [closed]

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

Solution 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)

Solution 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.

Solution 3:

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.