web-dev-qa-db-fra.com

Générer de la documentation Protobuf?

Quelqu'un connaît-il un bon outil pour générer de la documentation Google Protobuf à l'aide des fichiers source .proto?

documentationprotocolsprotocol-buffersdocumentation-generation
51
Markus K

Un plugin protobuf open source qui génère DocBook et PDF à partir des fichiers proto.

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

Avertissement: je suis l'auteur du plugin.

10
askldjd

[ Mise à jour : août 2017. Adapté à la réécriture complète de Go de protocol-gen-bug, actuellement 1.0.0-rc]

Le protoc-doc-gen, créé par @estan (voir aussi sa réponse précédente ) fournit un moyen simple et efficace de générer votre documentation en html, json, markdown, pdf et autres formats.

Il y a un certain nombre de choses supplémentaires que je dois mentionner:

  1. estan n'est plus le mainteneur de protoc-doc-gen, mais pseudomuto est
  2. Contrairement à ce que j'ai lu sur différentes pages, il est possible d'utiliser un formatage en ligne riche (gras/italique, liens, extraits de code, etc.) dans les commentaires
  3. protoc-gen-doc a été complètement réécrit dans Go et utilise désormais Docker pour la génération (au lieu de apt-get)

Le référentiel est maintenant ici: https://github.com/pseudomuto/protoc-gen-doc

Pour démontrer le deuxième point, j'ai créé un exemple de référentiel pour générer automatiquement la documentation Dat Project Hypercore Protocol dans un format sympa.

Vous pouvez afficher diverses options de génération de sortie html et markdown sur (ou regardez ici pour un exemple de démarque sur SO):

Le script TravisCI qui fait toute l'automatisation est aussi simple que .travis.yml fichier:

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 [~ # ~] : Le protocole hypercore est l'un des principaux spécifications de l'écosystème Projet Dat de modules de création d'applications peer-to-peer décentralisées. J'ai utilisé leur .proto fichier pour montrer les concepts)

8
Arnold Schrijver

En plus de la réponse de askldjd, je voudrais souligner mon propre outil sur https://github.com/estan/protoc-gen-doc . Il s'agit également d'un plugin de compilateur de tampon de protocole, mais peut générer du HTML, MarkDown ou DocBook hors de la boîte. Il peut également être personnalisé à l'aide de modèles de moustache pour générer le format texte que vous souhaitez.

Les commentaires sur la documentation sont écrits à l'aide de /** ... */ ou /// ....

8
estan

Le fil est ancien, mais la question semble toujours d'actualité. J'ai eu de très bons résultats avec doxygen + proto2cpp . proto2cpp fonctionne comme un filtre d'entrée pour doxygen.

6
damjan

Doxygen prend en charge les soi-disant filtres d'entrée, qui vous permettent de transformer le code en quelque chose que doxygen comprend. L'écriture d'un tel filtre pour transformer l'IDL Protobuf en code C++ (par exemple) vous permettrait d'utiliser toute la puissance de Doxygen dans les fichiers .proto. Voir l'article 12 de la FAQ Doxygen .

J'ai fait quelque chose de similaire pour CMake, le filtre d'entrée transforme simplement les macros et les fonctions CMake en déclarations de fonction C. Vous pouvez le trouver ici .

6
Sascha

Dans Protobuf 2.5, les commentaires "//" que vous placez dans vos fichiers .proto en font réellement le code source Java comme commentaires Javadoc. Plus précisément, le compilateur de protocole prendra votre "//" des commentaires comme celui-ci:

// 
// Message level comments
message myMsg {

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

ira dans vos fichiers source Java source. Pour une raison quelconque, le protocole inclut les commentaires Javadoc dans <pre> Mots clés. Mais dans l'ensemble, c'est une nouvelle fonctionnalité intéressante de la v2.5.

4
peterh

Étant donné que le fichier .proto est principalement une simple déclaration, je trouve généralement que le fichier source avec des commentaires en ligne est une documentation simple et efficace.

2
Flwyd