生成Protobuf文档？

Question

有没有人知道使用.proto源文件生成Google Protobuf文档的好工具？

Answer 1

一个开源的protobuf插件,可以从proto文件生成DocBook和PDF.

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

免责声明:我是该插件的作者.

Answer 2

在 Protobuf 2.5 中，您放入 .proto 文件中的“//”注释实际上将其作为 Javadoc 注释放入生成的 Java 源代码中。更具体地说，protoc 编译器将采用您的“//”注释，如下所示：

// 
// Message level comments
message myMsg {

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

将进入您生成的 java 源文件。出于某种原因，protoc 将 Javadoc 注释包含在<pre>标签中。但总而言之，它是 v2.5 中的一个不错的新功能。

Answer 3

[ 更新:2017年8月.适应完整的Go重写protoc-gen-bug,目前1.0.0-rc]

的protoc-doc-gen,由@estan创建(另见他刚才的答复)提供了生成HTML,JSON,降价,PDF等格式的文档,你的一个很好的和简单的方法.

我还应该提到一些额外的事情:

1. estan不再的维护者protoc-doc-gen,但pseudomuto是
2. 相较于我读过各种网页它是可以使用注释中丰富的内嵌格式(粗体/斜体,链接,代码片段等)
3. protoc-gen-doc已经在Go中完全重写,现在使用Docker进行生成(而不是apt-get)

存储库现在位于:https://github.com/pseudomuto/protoc-gen-doc

为了演示第二点,我创建了一个示例存储库,以一种很好的格式自动生成Dat Project Hypercore Protocol文档.

您可以在(或在此处查看SO上的降价示例)查看各种html和markdown输出生成选项:

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

执行所有自动化的TravisCI脚本就是这个简单的.travis.yml文件:

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:该多核协议是核心规范之一的Dat项目模块的生态系统,用于创建分散的对等应用程序我用他们..proto文件证明的概念)

Answer 4

除了askldjd的答案之外,我想在https://github.com/estan/protoc-gen-doc上指出我自己的工具.它也是一个协议缓冲区编译器插件,但可以开箱即用生成HTML,MarkDown或DocBook.它也可以使用Mustache模板进行自定义,以生成您喜欢的任何基于文本的格式.

文档注释使用/** ... */或编写/// ....

Answer 5

Doxygen支持所谓的输入过滤器,它允许您将代码转换为doxygen理解的内容.编写这样的过滤器以将Protobuf IDL转换为C++代码(例如)将允许您在.proto文件中使用Doxygen的全部功能.参见Doxygen FAQ的第12项.

我为CMake做了类似的事情,输入过滤器只是将CMake宏和函数转换为C函数声明.你可以在这里找到它.

Answer 6

线程很旧,但问题似乎仍然相关.doxygen + proto2cpp我的效果非常好.proto2cpp作为doxygen的输入过滤器.