Update samplegen readme (#240)

- show how to pass sample configs to samplegen as a standalone program
- show how to generate samples when execute client library generator, either as protoc plugin or in a docker image
- reflect that deprecating gapic config is work in progress

README.md

@@ -83,6 +83,12 @@ The configuration supported by the plugin option includes:
     * Defaults to empty, which is essentially the GA release level.
     * Acceptable values are `alpha` and `beta`.
 
+  * `sample`: path to sample configuration files.
+    * This is used for sample generation. Refer to [sample generation guide](./cmd/gen-go-sample/README.md) for more details.
+
+  * `gapic`: path to the legacy gapic configuration file.
+    * This is used for sample generation only. Both gapic config itself and this option will be deprecated soon. Refer to [sample generation guide](./cmd/gen-go-sample/README.md) for more details.
+
 Bazel
 -----
 
@@ -152,7 +158,7 @@ An equivalent invocation using `gapic.sh` is:
 $ gapic.sh \
   --image gcr.io/gapic-images/gapic-generator-go \
   --in /abs/path/to/protos \
-  --out $GOPATH/src\ 
+  --out $GOPATH/src \
   --go-gapic-package "<github.com/package/import/path;name>"
 ```
 

cmd/gen-go-sample/README.md

@@ -6,10 +6,13 @@ A generator for samples showing how to make API calls with clients generated by
 Prerequisites
 ===========================
 - proto descriptors of an API
-- sample configuration written in gapic config*
+- sample configurations
+- gapic config*
 
-Note: We are in the process of moving sample configuration out of gapic config into a separate sample config yaml file.
-Refer to [sample config spec](https://github.com/googleapis/gapic-generator/blob/d633cd88ca98320ab921eafebd93942fffe5fed4/src/main/proto/com/google/api/codegen/samplegen/v1p2/sample_config_v1p2.proto) for how to config a sample. Before that, samples can be configured using [gapic config](https://github.com/googleapis/gapic-generator/blob/d633cd88ca98320ab921eafebd93942fffe5fed4/src/main/proto/com/google/api/codegen/config.proto).
+Note: The gapic config is necessary to convey information about resource names and longrunning operations. There is currently work in progress to make the sample generator
+consume protobuf annotations instead of gapic config. After the work is finished, gapic config will no longer be needed.
+
+Refer to [sample config spec](https://github.com/googleapis/gapic-generator/blob/d633cd88ca98320ab921eafebd93942fffe5fed4/src/main/proto/com/google/api/codegen/samplegen/v1p2/sample_config_v1p2.proto) for how to config a sample.
 
 Installation
 ===========================
@@ -24,11 +27,15 @@ go install ./cmd/gen-go-sample
 
 Invocation
 ===========================
+### Run sample generator as a standalone program
 ```
 gen-go-sample \
   -clientpkg 'url/to/client/pkg;name' \
   -gapic 'path/to/gapic/config/some_gapic.yaml' \
   -o [OUTPUT_DIR] \
+  -desc 'path/to/proto/descriptor.desc' \
+  -sample path/to/sample.yaml \
+  -sample path/to/another_sample.yaml \
   -desc 'path/to/proto/descriptor.desc'
 ```
 
@@ -40,23 +47,60 @@ gen-go-sample \
   -gapic "path/to/gapic/config/some_gapic.yaml" \
   -o [OUTPUT_DIR] \
   -desc <(protoc -o /dev/stdout --include_imports -I "$COMMON_PROTO" -I a.proto b.proto)
+  -sample path/to/sample.yaml \
+  -sample path/to/another_sample.yaml \
 ```
 
 - The `$COMMON_PROTO` variable represents a path to the [googleapis/api-common-protos](https://github.com/googleapis/api-common-protos) directory to import the configuration annotations.
 - The -o flag is necessary because we need to know where generated files will live.
 
-For example, to generate samples for the language API, run
+For example, to generate all the samples for the language API, run
 ```
 export GOOGLEAPIS=/tmp/googleapis
 git clone [email protected]:googleapis/googleapis.git $GOOGLEAPIS
 
 export COMMON_PROTO=/tmp/common-protos
 git clone [email protected]:googleapis/api-common-protos.git $COMMON_PROTOS
 
+for sample in $GOOGLEAPIS/google/cloud/language/v1/samples/*.yaml
+do
+  samples+=('-sample')
+  samples+=($sample)
+done
+
 gen-go-sample \
   -clientpkg 'cloud.google.com/go/language/apiv1;language' \
   -gapic "$GOOGLEAPIS/google/cloud/language/v1/language_gapic.yaml" \
-  -o /tmp/language/samples/v1
-  -desc <(protoc -o /dev/stdout --include_imports -I "$COMMON_PROTO" "$GOOGLEAPIS"/google/cloud/language/v1/*.proto)
+  -o /tmp/language/samples/v1 \
+  -desc <(protoc -o /dev/stdout --include_imports -I "$COMMON_PROTO" "$GOOGLEAPIS"/google/cloud/language/v1/*.proto) \
+  ${samples[@]}
+```
+
+### Run sample generator as an add-on of the client library generator
+The sample generator also works as an add-on of the client library generator. All you need to do to enable sample generation
+is passing sample configurations and gapic config (for the time being) to the generator.
+
+When executing the client library generator as a protoc plugin, run
+```bash
+$ protoc -I $API_COMMON_PROTOS \
+  --go_gapic_out [OUTPUT_DIR] \
+  --go_gapic_opt 'go-gapic-package=package/path/url;name' \
+  --go_gapic_opt 'sample=path/to/sample/config.yaml,sample=path/to/another/sample/config.yaml' \
+  --go_gapic_opt 'gapic=path/to/gapic/config.yaml' \
+  a.proto b.proto
 ```
 
+When executing the client library generator in a docker container, run
+```bash
+$ docker run \
+  --rm \
+  --user $UID \
+  --mount type=bind,source=</abs/path/to/protos>,destination=/in,readonly \
+  --mount type=bind,source=</abs/path/to/configs>,destination=/conf,readonly \
+  --mount type=bind,source=$GOPATH/src,destination=/out/ \
+  gcr.io/gapic-images/gapic-generator-go \
+  --go-gapic-package "github.com/package/import/path;name" \
+  --sample "path/to/sample/config.yaml" \
+  --sample "path/to/another/sample/config.yaml" \
+  --gapic "path/to/gapic/config.yaml"
+```

cmd/gen-go-sample/test.bash

@@ -27,8 +27,15 @@ fi
 
 OUT=${OUT:-testdata/out}
 
+for sample in $GOOGLEAPIS/google/cloud/language/v1/samples/*.yaml
+do
+	samples+=('-sample')
+	samples+=($sample)
+done
+
 ./gen-go-sample $* \
   -clientpkg 'cloud.google.com/go/language/apiv1;language' \
   -gapic "$GOOGLEAPIS/google/cloud/language/v1/language_gapic.yaml" \
   -o "$OUT" \
-  -desc <(protoc -o /dev/stdout --include_imports -I "$COMMON_PROTO" -I "$GOOGLEAPIS" "$GOOGLEAPIS"/google/cloud/language/v1/*.proto)
+  -desc <(protoc -o /dev/stdout --include_imports -I "$COMMON_PROTO" -I "$GOOGLEAPIS" "$GOOGLEAPIS"/google/cloud/language/v1/*.proto) \
+  ${samples[@]}