Generate Protobuf documentation? [closed]

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 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 4

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