Generate Protobuf documentation?

documentation protocols protocol-buffers documentation-generation

28,323

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:

estan is no longer the maintainer of protoc-doc-gen, but pseudomuto is
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
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.

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

Solution 5

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.

View more solutions

28,323