Skip to content

Commit

Permalink
feat: Infrastructure for generating protobuf docs (#6046)
Browse files Browse the repository at this point in the history 
This adds Docker instructions and a Gradle configuration to generate
markdown documentation for Protobuf files at
`proto/proto-backplane-grpc/build/generated/source/proto/main/proto-doc`.
The new docs get generated as a part of the `./gradlew
:proto:proto-backplane-grpc:generateProtobuf` Gradle task. We should
assess whether flight should receive the same treatment.
  • Loading branch information
@alexpeters1208
alexpeters1208 authored Sep 11, 2024
1 parent 41d5cc0 commit 30894e1
Show file tree
Hide file tree
Showing 3 changed files with 160 additions and 2 deletions.
2 changes: 1 addition & 1 deletion docker/registry/protoc-base/gradle.properties
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
io.deephaven.project.ProjectType=DOCKER_REGISTRY
deephaven.registry.imageName=ghcr.io/deephaven/protoc-base:latest
deephaven.registry.imageId=ghcr.io/deephaven/protoc-base@sha256:70f31806515b4d160ab6ddf9b7b6612441b5918b0f1c5586ee2cc9ad8a4c81da
deephaven.registry.imageId=ghcr.io/deephaven/protoc-base@sha256:7b43037ce0cf2a82aff73605a689754620791238ed598b7ae41aa5b225a27ccf
# TODO(deephaven-base-images#54): arm64 native image for cpp-client-base
deephaven.registry.platform=linux/amd64
156 changes: 155 additions & 1 deletion proto/proto-backplane-grpc/Dockerfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@ RUN set -eux; \
mkdir -p /generated/go; \
mkdir -p /generated/python; \
mkdir -p /generated/cpp; \
mkdir -p /generated/proto-doc/single-html; \
mkdir -p /generated/proto-doc/single-md; \
mkdir -p /generated/proto-doc/multi-html; \
mkdir -p /generated/proto-doc/multi-md; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-grpc=/opt/java/bin/protoc-gen-grpc-java \
--java_out=/generated/java \
Expand Down Expand Up @@ -84,4 +88,154 @@ RUN set -eux; \
/includes/deephaven/proto/partitionedtable.proto \
/includes/deephaven/proto/config.proto \
/includes/deephaven/proto/hierarchicaltable.proto \
/includes/deephaven/proto/storage.proto;
/includes/deephaven/proto/storage.proto; \
# proto-doc-gen does not support writing multiple proto files to multiple docs, must break up command \
# we are going to generate 4 sets of docs - single html, multi html, single markdown, multi markdown \
# first, single html \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/single-html \
--doc_opt=html,index.html \
-I/includes \
/includes/deephaven/proto/*.proto; \
# next, single markdown \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/single-md \
--doc_opt=markdown,index.md \
-I/includes \
/includes/deephaven/proto/*.proto; \
# then, multi html \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-html \
--doc_opt=html,ticket.html \
-I/includes \
/includes/deephaven/proto/ticket.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-html \
--doc_opt=html,console.html \
-I/includes \
/includes/deephaven/proto/console.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-html \
--doc_opt=html,object.html \
-I/includes \
/includes/deephaven/proto/object.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-html \
--doc_opt=html,session.html \
-I/includes \
/includes/deephaven/proto/session.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-html \
--doc_opt=html,table.html \
-I/includes \
/includes/deephaven/proto/table.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-html \
--doc_opt=html,application.html \
-I/includes \
/includes/deephaven/proto/application.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-html \
--doc_opt=html,inputtable.html \
-I/includes \
/includes/deephaven/proto/inputtable.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-html \
--doc_opt=html,partitionedtable.html \
-I/includes \
/includes/deephaven/proto/partitionedtable.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-html \
--doc_opt=html,config.html \
-I/includes \
/includes/deephaven/proto/config.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-html \
--doc_opt=html,hierarchicaltable.html \
-I/includes \
/includes/deephaven/proto/hierarchicaltable.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-html \
--doc_opt=html,storage.html \
-I/includes \
/includes/deephaven/proto/storage.proto; \
# finally, multi md \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-md \
--doc_opt=markdown,ticket.md \
-I/includes \
/includes/deephaven/proto/ticket.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-md \
--doc_opt=markdown,console.md \
-I/includes \
/includes/deephaven/proto/console.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-md \
--doc_opt=markdown,object.md \
-I/includes \
/includes/deephaven/proto/object.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-md \
--doc_opt=markdown,session.md \
-I/includes \
/includes/deephaven/proto/session.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-md \
--doc_opt=markdown,table.md \
-I/includes \
/includes/deephaven/proto/table.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-md \
--doc_opt=markdown,application.md \
-I/includes \
/includes/deephaven/proto/application.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-md \
--doc_opt=markdown,inputtable.md \
-I/includes \
/includes/deephaven/proto/inputtable.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-md \
--doc_opt=markdown,partitionedtable.md \
-I/includes \
/includes/deephaven/proto/partitionedtable.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-md \
--doc_opt=markdown,config.md \
-I/includes \
/includes/deephaven/proto/config.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-md \
--doc_opt=markdown,hierarchicaltable.md \
-I/includes \
/includes/deephaven/proto/hierarchicaltable.proto; \
/opt/protoc/bin/protoc \
--plugin=protoc-gen-doc=/usr/local/bin/protoc-gen-doc \
--doc_out=generated/proto-doc/multi-md \
--doc_opt=markdown,storage.md \
-I/includes \
/includes/deephaven/proto/storage.proto; \
4 changes: 4 additions & 0 deletions proto/proto-backplane-grpc/build.gradle
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ configurations {
python {}
go {}
cpp {}
protoDocs {}
}

dependencies {
Expand Down Expand Up @@ -88,6 +89,9 @@ artifacts {
cpp(layout.buildDirectory.dir('generated/source/proto/main/cpp')) {
builtBy generateProtobuf
}
protoDocs(layout.buildDirectory.dir('generated/source/proto/main/proto-doc')) {
builtBy generateProtobuf
}
}


Expand Down

0 comments on commit 30894e1

Please sign in to comment.