Docker (#64)

.circleci/config.yml

@@ -14,7 +14,7 @@ workflows:
 jobs:
   unit-3.6:
     docker:
-      - image: 'python:3.6'
+      - image: python:3.6-slim
     steps:
       - checkout
       - run:
@@ -36,7 +36,7 @@ jobs:
           when: always
   unit-3.7:
     docker:
-      - image: 'python:3.7'
+      - image: python:3.7-slim
     steps:
       - checkout
       - run:
@@ -58,17 +58,17 @@ jobs:
           when: always
   showcase:
     docker:
-      - image: 'python:3.7'
+      - image: python:3.7-slim
     steps:
       - checkout
       - run:
-          name: Install nox.
-          command: pip install --pre nox-automation
-      - run:
-          name: Install pandoc and unzip.
+          name: Install system dependencies.
           command: |
             apt-get update
-            apt-get install -y pandoc unzip
+            apt-get install -y curl pandoc unzip
+      - run:
+          name: Install nox.
+          command: pip install --pre nox-automation
       - run:
           name: Install protoc 3.6.1.
           command: |
@@ -94,7 +94,7 @@ jobs:
           command: nox -s showcase
   docs:
     docker:
-      - image: 'python:3.6'
+      - image: python:3.6-slim
     steps:
       - checkout
       - run:

.dockerignore

@@ -0,0 +1,61 @@
+# Version control scaffolding
+.git
+.gitignore
+
+# Docker scaffolding
+Dockerfile
+.dockerignore
+
+# Python scaffolding
+*.py[cod]
+*.egg
+*.egg-info
+dist
+build
+eggs
+parts
+bin
+var
+sdist
+develop-eggs
+.installed.cfg
+lib
+lib64
+__pycache__
+
+# Installer logs
+pip-log.txt
+
+# Unit test / coverage reports
+.coverage
+.nox
+.tox
+.cache
+.pytest_cache
+htmlcov
+
+# Translations
+*.mo
+
+# Mac
+.DS_Store
+
+# Mr Developer
+.mr.developer.cfg
+.project
+.pydevproject
+
+# JetBrains
+.idea
+
+# Built documentation
+docs/_build
+docs/_build_doc2dash
+
+# Virtual environment
+env/
+coverage.xml
+
+# Make sure a generated file isn't accidentally committed.
+pylintrc
+pylintrc.test

.gitignore

@@ -53,9 +53,6 @@ docs/_build_doc2dash
 env/
 coverage.xml
 
-# System test environment variables.
-system_tests/local_test_setup
-
 # Make sure a generated file isn't accidentally committed.
 pylintrc
 pylintrc.test

Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.7-slim
+
+# Install system packages.
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends \
+    pandoc \
+  && rm -rf /var/lib/apt/lists/*
+
+# Add protoc and our common protos.
+COPY --from=gcr.io/gapic-images/api-common-protos:latest /usr/local/bin/protoc /usr/local/bin/protoc
+COPY --from=gcr.io/gapic-images/api-common-protos:latest /protos/ /protos/
+
+# Add our code to the Docker image.
+ADD . /usr/src/gapic-generator-python/
+
+# Install the tool within the image.
+RUN pip install /usr/src/gapic-generator-python
+
+# Define the generator as an entry point.
+ENTRYPOINT protoc --proto_path=/protos/ --proto_path=/in/ \
+                  --python_gapic_out=/out/ \
+                  `find /in/ -name *.proto`

docs/conf.py

@@ -24,10 +24,14 @@
 author = 'Luke Sneeringer'
 
 # The short X.Y version
-version = '0.0.4'
+version = os.environ.get('CIRCLE_TAG', 'latest')
 # The full version, including alpha/beta/rc tags
-release = '0.0.4'
+release = os.environ.get('CIRCLE_TAG', 'latest')
 
+# Replace |version| in the docs with the actual version string.
+rst_epilog = """
+.. |version| replace:: {version}
+""".format(version=version)
 
 # -- General configuration ---------------------------------------------------
 

docs/getting-started/_example.rst

@@ -0,0 +1,20 @@
+If you want to experiment with an already-existing API, one example is
+available. (Reminder that this is still considered experimental, so apologies
+for this part being a bit strange.)
+
+You need to clone the `googleapis`_ repository from GitHub, and change to
+a special branch:
+
+.. code-block:: shell
+
+  $ git clone git@github.com:googleapis/googleapis.git
+  $ cd googleapis
+  $ git checkout --track -b input-contract origin/input-contract
+  $ cd ..
+
+The API available as an example (thus far) is the `Google Cloud Vision`_ API,
+available in the ``google/cloud/vision/v1/`` subdirectory. This will be used
+for the remainder of the examples on this page.
+
+.. _googleapis: https://github.com/googleapis/googleapis/tree/input-contract
+.. _Google Cloud Vision: https://cloud.google.com/vision/

docs/getting-started/_usage_intro.rst

@@ -0,0 +1,6 @@
+To use this plugin, you will need an API which is specified using
+protocol buffers. Additionally, this plugin makes some assumptions at the
+margins according to `Google API design conventions`_, so following those
+conventions is recommended.
+
+.. _Google API design conventions: https://cloud.google.com/apis/design/

docs/getting-started/_verifying.rst

@@ -0,0 +1,50 @@
+Verifying the Library
+---------------------
+
+Once you have compiled a client library, whether using a Docker image or
+a local installation, it is time for the fun part: actually running it!
+
+Create a virtual environment for the library:
+
+.. code-block:: shell
+
+  $ virtualenv ~/.local/client-lib --python=`which python3.7`
+  $ source ~/.local/client-lib/bin/activate
+
+Next, install the library:
+
+.. code-block:: shell
+
+  $ cd /dest/
+  $ pip install --editable .
+
+Now it is time to play with it!
+Here is a test script:
+
+.. code-block:: python
+
+  # This is the client library generated by this plugin.
+  from google.cloud import vision
+
+  # Instantiate the client.
+  #
+  # If you need to manually specify credentials, do so here.
+  # More info: https://cloud.google.com/docs/authentication/getting-started
+  #
+  # If you wish, you can send `transport='grpc'` or `transport='http'`
+  # to change which underlying transport layer is being used.
+  ia = vision.ImageAnnotator()
+
+  # Send the request to the server and get the response.
+  response = ia.batch_annotate_images({
+      'requests': [{
+          'features': [{
+              'type': vision.types.image_annotator.Feature.Type.LABEL_DETECTION,
+          }],
+          'image': {'source': {
+              'image_uri': 'https://s3.amazonaws.com/cdn0.michiganbulb.com'
+                           '/images/350/66623.jpg',
+          }},
+      }],
+  })
+  print(response)

docs/getting-started/docker-shortcut.rst

@@ -0,0 +1,28 @@
+:orphan:
+
+.. _docker-shortcut:
+
+Docker Shortcut Script
+----------------------
+
+Because code generation requires two mounts from the host machine into
+the Docker image, and because the paths are somewhat pedantic, you may
+find this shortcut script to be handy:
+
+.. literalinclude:: ../../gapic.sh
+    :language: shell
+
+Place it somewhere on your system, marked executable.
+
+Once available, it can be invoked using:
+
+.. code-block:: shell
+
+    # This is assumed to be from the "proto root" directory.
+    $ gapic.sh --image gcr.io/gapic-images/gapic-generator-python \
+        --in path/to/src/protos/
+        --out dest/
+
+
+It will work not only with the Python code generator, but all of our code
+generators that implement this Docker interface.