generate docs for protos that import dependencies

[timleung22]

I installed the latest docker image

bash-3.2$ docker images pseudomuto/protoc-gen-doc REPOSITORY TAG IMAGE ID CREATED SIZE pseudomuto/protoc-gen-doc latest 97f2a3be38ef 2 months ago 88.2MB

I have a proto that imports a bunch of protos. For example, in examples.proto,

import "google/protobuf/timestamp.proto"; import "google/protobuf/wrappers.proto"; import "google/protobuf/empty.proto"; import "google/api/annotations.proto"; import "foo/protobuf/my_well_known_types.proto"; import "foo/api/swagger_annotations.proto"; import "foo/common/dictionary/foo_types.proto";

message Example { int64 exampleId = 1; string exampleAlternateId = 2; google.protobuf.Timestamp exampleTimestampField = 3; string exampleStringField = 4; int32 exampleIntField = 5; int64 exampleLongField = 6; double exampleDoubleField = 7; foo.protobuf.BigDecimal exampleBigDecimal = 8; foo.protobuf.BigInteger exampleBigInteger = 9; google.protobuf.StringValue exampleNullableStringField = 10; google.protobuf.Int32Value exampleNullableIntField = 11; google.protobuf.Int64Value exampleNullableLongField = 12; google.protobuf.DoubleValue exampleNullableDoubleField = 13; Example childExample = 14; }

And I got this error when running docker run --rm -v $(pwd)/build/docs:/out -v $(pwd)/src/main/proto/example:/protos pseudomuto/protoc-gen-doc

google/api/annotations.proto: File not found. foo/protobuf/my_well_known_types.proto: File not found. foo/api/swagger_annotations.proto: File not found. foo/common/dictionary/foo_types.proto: File not found.

followed with a bunch of "was not found or had errors" and "is not defined" errors. The same error was produced with the -doc_opt=:google/,foo/protobuf/,foo/api/,foo/common/dictionary/ option trying to exclude them.

[timleung22]

I was able to resolve this issue with the use of -I / --proto_path which includes all the proto sources this particular proto depends on. Not ideal but at least, get the job done.

protoc --plugin=protoc-gen-doc=/Users/trpfe96/go/bin/protoc-gen-doc --doc_out=./build/doc --doc_opt=html,index.html --proto_path=$(pwd)/build/extracted-include-protos/main/ --proto_path=$(pwd)/src/main/proto/trp/ea/fusion/example/ example_service.proto

But the documentation didn't mention how to use the --proto_path option when using the docker container.

[c0rnyc0rny]

hey @timleung22 i had the same problem and found the same solution as you. but an extension or a how to for the docker-image would be nice

[mesiu]

Is there anyway to pass the --proto_path option when using the docker container?

[nnutter]

Is there anyway to pass the --proto_path option when using the docker container?

Looks like entrypoint.sh passes along args so should be able to just pass them in to the docker run. If not, you can override --entrypoint and do whatever you want.

[commonquail]

I got this working:

$ unzip $HOME/.m2/repository/com/google/api/grpc/proto-google-common-protos/1.14.0/proto-google-common-protos-1.14.0-sources.jar \
    'google/*'
$ docker run --rm \
    -v $(pwd)/out:/out \
    -v $(pwd)/protos:/protos:ro \
    -v $(pwd)/google:/google:ro \
    pseudomuto/protoc-gen-doc \
    --proto_path=.

Because entrypoint.sh overrides the default proto_path of the working directory I had to explicitly re-include it. Playing around inside the container indicates it would probably have worked perfectly if entrypoint.sh had not set --proto_path.

[strowk]

Theoretically, docker image can do apt-get update && apt-get install git && git clone https://github.com/protocolbuffers/protobuf wellKnown and have in entrypoint something to automatically append wellKnown folder to proto_path (better also to support passing proto_path from docker run, so not override, but parse and append if necessary).

The problem which I encountered is that

protoc  --doc_out=/out --doc_opt=markdown,README.md --proto_path protos --proto_path wellKnown protos/*.proto

does not give timestamp's definitions to README.md, only

protoc  --doc_out=/out --doc_opt=markdown,README.md --proto_path protos --proto_path wellKnown protos/*.proto wellKnown/google/protobuf/timestamp.proto

does that.

Even though my proto already referencing google/protobuf/timestamp in import. So this means I'd have to duplicate the dependency in proto and whatever CI would run autogeneration.

[larspaulsen]

Thank you so much for sharing this work-a-round as is literally saved my day, without this info one is simply stuck.