This library contains the java model representing the json output of the protoc-gen-doc tool.

URLs

Do you want to improve this page? Please edit it on GitHub.

Usage

The library is hosted on maven central:

Listing 1. Maven coordinates of the project (xml notation)
<dependency>
  <groupId>com.unblu.protodoc4j</groupId>
  <artifactId>protodoc4j</artifactId>
  <version>{last-stable-versions}</version>
</dependency>
Listing 2. Maven coordinates of the project (single line notation)
com.unblu.protodoc4j:protodoc4j:{last-stable-versions}

Run the protoc-gen-doc tool to generate the JSON:

Listing 3. Example command to run protoc with the protoc-gen-doc plugin
protoc --plugin=__path-to__/protoc-gen-doc \
    --doc_out=./doc \
    --doc_opt=json,documentation.json \
    --proto_path=src/main/proto \
    src/main/proto/**/*.proto

This will generate a file similar to the example.json file.

And use the model classes together with jackson to parse the created documentation.json file.

Source Code

As for any java project, the source code of the plugin is available in the src/ folder.

Build

This project is using gradle.

Command to build the sources locally:

./gradlew build

Command to run the tool locally, passing the --help argument to the application:

./gradlew run --args="--help"

Command to deploy to your local maven repository:

./gradlew publishToMavenLocal

Command to build the documentation page:

./gradlew asciidoctor

The output of this command is an HTML page located at <git repo root>/build/docs/html5/index.html.

For project maintainers

Following properties are expected to be set (for example in ~/.gradle/gradle.properties):

  • signing.gnupg.keyName

  • signing.gnupg.passphrase

  • ossSonatypeUsername

  • ossSonatypePassword

Command to upload the documentation page on GitHub pages:

./gradlew gitPublishPush

Command to perform a release:

./gradlew release -Prelease.useAutomaticVersion=true

Using ssh-agent

Some tasks requires to push into the distant git repository (release task or updating the gh-pages branch). If they are failing with errors like this:

org.eclipse.jgit.api.errors.TransportException: ... Permission denied (publickey).

Then ssh-agent can be used.

eval `ssh-agent -s`
ssh-add ~/.ssh/id_rsa

(source for this approach)

Get in touch

Use the ProtoDoc4j issue tracker on GitHub.

License

Apache 2.0 License