web-dev-qa-db-ja.com

Protobufドキュメントを生成しますか？

.protoソースファイルを使用してGoogle Protobufドキュメントを生成する優れたツールを知っている人はいますか？

documentationprotocolsprotocol-buffersdocumentation-generation
51
Markus K

DocBookとPDFをprotoファイルから生成するオープンソースのprotobufプラグイン。

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

免責事項：私はプラグインの作成者です。

10
askldjd

[更新：2017年8月。Protoc-gen-bugのGoの完全な書き換えに対応。現在は1.0.0-rc]

@estanによって作成されたprotoc-doc-gen（ 以前の回答 も参照）は、html、json、markdown、pdf、およびその他の形式でドキュメントを生成するための優れた簡単な方法を提供します。

私が言及すべき追加の事柄がいくつかあります：

  1. estan はprotoc-doc-genのメンテナではなくなりましたが、- pseudomuto は
  2. 私がさまざまなページで読んだものとは対照的に、コメント内で豊富なインラインフォーマット（太字/斜体、リンク、コードスニペットなど）を使用することができます。
  3. protoc-gen-docはGoで完全に書き直され、現在はapt-getではなくDockerを使用して生成されています。

リポジトリがここにあります： https://github.com/pseudomuto/protoc-gen-doc

2番目のポイントを示すために、ナイス形式で Dat Project Hypercore Protocolのドキュメントを自動生成するサンプルリポジトリを作成しました。

さまざまなhtmlおよびmarkdown出力生成オプションを次の場所で表示できます（またはSOのマークダウンの例については ここ を参照してください）。

すべての自動化を行う 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 [〜＃〜]：hypercore プロトコルは1つです Dat Project 分散型ピアツーピアアプリケーションを作成するためのモジュールのエコシステムのコア仕様の一部です。概念を示すために、それらの.protoファイルを使用しました）

8
Arnold Schrijver

Askldjdの回答に加えて、 https://github.com/estan/protoc-gen-doc で自分のツールを指摘したいと思います。また、プロトコルバッファコンパイラプラグインですが、HTML、MarkDown、DocBookをそのまま生成できます。 Mustacheテンプレートを使用してカスタマイズして、好きなテキストベースのフォーマットを生成することもできます。

ドキュメントのコメントは/** ... */または/// ...。

8
estan

スレッドは古いですが、質問はまだ関連があるようです。 doxygen + proto2cpp で非常に良い結果が得られました。 proto2cppは、doxygenの入力フィルターとして機能します。

6
damjan

Doxygenは、いわゆる入力フィルターをサポートしています。これにより、コードをdoxygenが理解できるものに変換できます。 Protobuf IDLをC++コードに変換するためのそのようなフィルターを作成すると（たとえば）、. protoファイルでDoxygenの全機能を使用できるようになります。 Doxygen FAQ の項目12を参照してください。

CMakeについても同様のことを行いました。入力フィルターはCMakeマクロと関数をC関数宣言に変換するだけです。あなたはそれを見つけることができます ここ 。

6
Sascha

Protobuf 2.5では、.protoファイルに入力した「//」コメントは、実際には、生成されたJava Javadocコメントとしてのソースコードになります。より具体的には、protocコンパイラは「//」を受け取りますこのようなコメント：

// 
// Message level comments
message myMsg {

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

生成されたJavaソースファイルに移動します。何らかの理由で、protocはJavadocコメントを<pre>タグで囲みます。しかし、全体として、v2.5の素晴らしい新機能です。

4
peterh

.protoファイルはほとんどが宣言なので、通常、インラインコメントを含むソースファイルは簡単で効果的なドキュメントであることがわかります。

2
Flwyd