使用proto-doc-gen生成ProtoBuffers文档

protoc-gen-doc是一个protobuf的编译器protoc的一个插件，可以用来从protobuffers的定义文件中提取注释，生成相应的文档。目前protoc-gen-doc支持proto2和proto3语法。

安装和使用

protoc-gen-doc是用go语言编写的，安装方式如下：

go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc

使用方式：

protoc --doc_out=./doc --doc_opt=html,index.html  proto/*.proto

执行上述命令的前提是protoc和protoc-gen-doc都已经安装，并且两者都可以在PATH环境变量中找到。

如果protoc-gen-doc不在PATH中，那么需要显示指定：

protoc \
  --plugin=protoc-gen-doc=./protoc-gen-doc \
  --doc_out=./doc \
  --doc_opt=html,index.html \
  proto/*.proto

protoc-gen-doc还支持生成markdown等格式：

protoc --doc_out=. --doc_opt=markdown,xx.md xx.proto

protoc-gen-doc是采用模板的方式来生成文档的。模板语法使用的是go语言模板库的语法。在生成HTML的时候，采用的模板是：https://github.com/pseudomuto/protoc-gen-doc/blob/master/resources/html.tmpl

html模板是作为resource编译进入protoc-gen-doc的可执行文件的，参考：https://github.com/pseudomuto/protoc-gen-doc/tree/master/resources

这意味着，我们可以撰写自定义的模板，让protoc-gen-doc来帮忙填充，一个例子是ASCIIDOC的模板:：https://github.com/pseudomuto/protoc-gen-doc/blob/master/examples/templates/asciidoc.tmpl

使用自定义模板：

protoc --doc_out=. --doc_opt=asciidoc.tmpl,xx.adoc xx.proto

上面的命令使用自定义目录asciidoc.tmpl生成xx.adoc文档。

关于如何撰写模板，其wiki上有一篇过时的文章https://github.com/pseudomuto/protoc-gen-doc/wiki/Custom-Templates-(outdated)。一个变通的办法是直接查看源代码：https://github.com/pseudomuto/protoc-gen-doc/blob/master/template.go，可以知道protoc-gen-doc定义了哪些模板变量。

（完）