Initial sample generation documentation (#184)

docker-entrypoint.sh

@@ -31,6 +31,10 @@ while [ -n "$1" ]; do
       elif [[ $1 == --gapic-* ]]; then
         PLUGIN_OPTIONS="$PLUGIN_OPTIONS,$1=$2"
         shift 2
+      elif [[ $1 == --samples* ]]; then
+        # --samples is a special option that all generators should recognize.
+        PLUGIN_OPTIONS="$PLUGIN_OPTIONS,$1=$2"
+        shift 2
       else
         # Ignore anything we do not recognize.
         shift

docs/getting-started/_samplegen.rst

@@ -0,0 +1,14 @@
+Generating Samples
+~~~~~~~~~~~~~~~~~~
+
+In addition to generating client libraries, the generator can also create standalone executable code samples.
+
+The user can specify individual sample config files or can pass paths to directories that contain sample configs. Directories are searched recursively, and any file that is not a sample config is ignored.
+
+..
+ TODO: provide documentation links when they are present
+
+A full description of the sample config, generated manifest, and generated samples is outside the scope of this documentation.
+We will provide links to such documentation when it is ready.
+
+Samples and manifests are always generated in a 'samples' subdir of the destination directory.

docs/getting-started/docker.rst

@@ -119,5 +119,21 @@ Perform the actual code generation step with ``docker run``:
     structure present in the imports of the proto files must be preserved
     beneath this for compilation to succeed.
 
+.. include:: _samplegen.rst
+
+.. code-block:: shell
+
+  # Multiple sample paths or directories can be passed simultaneously by duplicating
+  # the 'samples' option.
+  # If no 'samples' option is passed, the generator does not generate a manifest.
+  $ docker run \
+    --mount type=bind,source=$(pwd)/path/to/proto/dir,destination=/in/path/to/proto,readonly \
+    --mount type=bind,source=$(pwd)/dest/,destination=/out/ \
+    --rm \
+    --user $UID \
+    gcr.io/gapic-images/gapic-generator-python \
+    --samples path/to/sample/config.yaml \
+    --samples path/to/sample/dir/
+
 
 .. include:: _verifying.rst

docs/getting-started/local.rst

@@ -153,4 +153,18 @@ This plugin is invoked under the hood via. the ``--python_gapic_out`` switch.
   where it expects to find protos, and *order matters*. In this case,
   the common protos must come first, and then the path to the API being built.
 
+.. include:: _samplegen.rst
+
+.. code-block:: shell
+
+  # Multiple sample paths or directories can be passed simultaneously by duplicating
+  # the 'samples' option. Options are comma delimited.
+  # If no 'samples' option is passed, the generator does not generate a manifest.
+  $ protoc path/to/api/protos/*.proto \
+                --proto_path=../api-common-protos/ \
+                --proto_path=. \
+                --python_gapic_opt="samples=sample_config.yaml,samples=sample_dir/" \
+                --python_gapic_out=/dest/
+
+
 .. include:: _verifying.rst