Add new "quickstart" samples. by jmdobry · Pull Request #77 · GoogleCloudPlatform/ruby-docs-samples

jmdobry · 2016-09-29T01:34:13Z

These are intended to be simple examples that explicitly show:

Importing the client library
Instantiating a client
Making a single API call
Printing the result

Products covered:

BigQuery
- - sample
- - test
Datastore
- - sample
- - test
Language
- - sample
- - test
Logging
- - sample
- - test
Pub/Sub
- - sample
- - test
Speech
- - sample
- - test
Storage
- - sample
- - test
Translate
- - sample
- - test
Vision
- - sample
- - test

For reference:

Add new "quickstart" samples python-docs-samples#547
Add new "quickstart" samples. php-docs-samples#174
Add new "quickstart" samples. golang-samples#131
GoogleCloudPlatform/java-docs-samples (pending)
GoogleCloudPlatform/dotnet-docs-samples (pending)

jmdobry · 2016-10-04T19:38:22Z

@remi These 9 quickstart samples are *done, and are being pulled into docs from this branch. I'd love to write tests, but can you or @frankyn please help out on this front? I'm off writing these samples for 6 other languages...

*defined as: region tags, comments, variable names, method calls, printing output, etc. have been finalized and standardized across the quickstart samples for the other languages.

frankyn · 2016-10-06T19:05:11Z

I'll work on the tests needed for these quickstarts.

1. Added test for BigQuery quickstart 2. Updated information about quickstart in README.md

1. Removed unecessary space in bigquery quickstart spec

1. Updated quickstart.rb to be a global set of instructions 2. Updated spec/quickstart_spec.rb to be a minimal test. (There's only one function to test.)

1. Substituated single quotes for double quotes.

jmdobry · 2016-10-06T23:51:16Z

bigquery/README.md


+### Quickstart
+
+'''


What are these single quotes for?

That is a incorrectly typed symbol. (I meant to use an apostrophe). I since have removed them, because Remi and I decided not to have them in the README for now.

1. Added RSpec for quickstart.rb 2. Modified quickstart.rb to be a globally scopped.

1. Added spec/quickstart.rb to test quickstart.rb 2. Changed quickstart.rb to be globally scoped.

1. Fixed typo

beccasaurus · 2016-10-10T19:37:10Z

bigquery/spec/quickstart_spec.rb

+
+    # Run quickstart
+    expect {
+      load File::expand_path("quickstart.rb")


I love this! Let's just fix these to be File.expand_path sans the ::

Should also specify the full path to the quickstart relative to the spec directory (otherwise this uses the current working directory). So:

load File.expand_path("../quickstart.rb", __dir__)

Understood!

beccasaurus · 2016-10-10T19:38:27Z

bigquery/spec/quickstart_spec.rb

+
+  it "creates a new dataset" do
+    # Initialize test objects
+    gcloud_test_client = Google::Cloud.new ENV["GOOGLE_CLOUD_PROJECT"]


Small #nit - Align variable assignments

Alignment of variable assignments is a common Ruby idiom and it is particularly useful for improving the readability of our code samples. So let's try to be consistent and always align (when it makes sense to do so)

Understood.

beccasaurus · 2016-10-10T19:50:59Z

bigquery/spec/quickstart_spec.rb

+
+    expect(bigquery_test_client.dataset "my_new_dataset").not_to be nil
+
+    # Clean up


This won't run if any of the above expectations fail.

Any cleanup should be placed in an after block to ensure that it runs.

Because this example ensures that it runs no existing dataset (does the deletion before it runs the snippet code), I vote to remove this cleanup. Dataset will be left behind, but it will always be deleted before the example runs to ensure that the test setup is correct.

If someone outside of Google runs the test do they have to pay for the Bigquery dataset?

Yes, users pay for all Google Cloud Platform usage

beccasaurus · 2016-10-10T19:54:43Z

bigquery/quickstart.rb

+project_id = "YOUR_PROJECT_ID"
+
+# Instantiates a client
+gcloud = Google::Cloud.new project_id


Because we already have a comment with the wording "Instantiates a client", I don't think we need to call the BigQuery client bigquery_client. I really like the clarity this adds but no other samples use this working.

All samples on the client library website use bigquery not bigquery_client:
https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud/v0.20.1/google/cloud/bigquery

Also, we use bigquery in our code samples and never use a _client suffix:
https://github.com/GoogleCloudPlatform/ruby-docs-samples/blob/2016.09.29/bigquery/tables.rb#L24

Let's update the syntax of the quickstarts to look more idiomatic, like so:

# Instantiates a client gcloud = Google::Cloud.new project_id bigquery = gcloud.bigquery

@jmdobry Is it critically important for every quickstart to have variables suffixed with _client?

No other Ruby samples use this, including google-cloud-ruby quickstarts. I would like the quickstart code to be conventional with code seen everywhere else.

For example, google-cloud-ruby has a quickstart on its homepage at: https://googlecloudplatform.github.io/google-cloud-ruby/#/

require "google/cloud" gcloud = Google::Cloud.new "my-todo-project-id", "/path/to/keyfile.json" datastore = gcloud.datastore product = datastore.find "Product", 123

And all other google-cloud-ruby snippets follow the following template:

require "google/cloud" gcloud = Google::Cloud.new storage = gcloud.storage all_buckets = storage.buckets

beccasaurus · 2016-10-10T19:59:06Z

bigquery/spec/quickstart_spec.rb

+
+  it "creates a new dataset" do
+    # Initialize test objects
+    gcloud_test_client = Google::Cloud.new ENV["GOOGLE_CLOUD_PROJECT"]


Let's change these to just gcloud and bigquery like is used everywhere else.

I liked how explicit gcloud_test_client is when initially drafting these specs to be super clear and self-document how these specs work:
https://gist.github.com/remi/f3abdee163a20e56c4d678c10e088d09

But now that I'm going back and reading these... I'd like to use the simple, consistent gcloud and project_name variables for these)

#consistency #nit

beccasaurus · 2016-10-10T20:09:52Z

datastore/spec/quickstart_spec.rb

+      "Saved Task: Buy milk\n"
+    }.to_stdout
+
+    expect(datastore_test_client.find(task_key_test_client)).not_to be nil


Let's check that the sampletask's description is "Buy milk" in addition to verifying that the entity now exists

Thoughts...

it "creates a new entity" do gcloud = Google::Cloud.new ENV["GOOGLE_CLOUD_PROJECT"] datastore = gcloud.datastore sampletask = datastore.find "Task", "sampletask1" datastore.delete sampletask if sampletask expect(datastore.find "Task", "sampletask1").to be nil expect(Google::Cloud).to receive(:new).with("YOUR_PROJECT_ID").and_return gcloud expect { load File.expand_path("../quickstart.rb", __dir__) }.to output { "Saved Task: Buy milk\n" }.to_stdout sampletask = datastore.find "Task", "sampletask1" expect(sampletask).not_to be nil expect(sampletask["description"]).to eq "Buy milk" end

beccasaurus · 2016-10-10T20:16:49Z

language/spec/quickstart_spec.rb

+      "Text: Hello, world!\n"+
+      "Sentiment: 1.0, 0.6000000238418579\n"
+    ).to_stdout
+


Remove trailing space in example block

beccasaurus · 2016-10-10T20:17:02Z

language/spec/quickstart_spec.rb

+    expect {
+      load File::expand_path("quickstart.rb")
+    }.to output(
+      "Text: Hello, world!\n"+


Add space before +

beccasaurus · 2016-10-10T20:17:36Z

logging/quickstart.rb

+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+def run_quickstart


Remove method wrappers for samples, just wrap in [START... and [END... region comments

beccasaurus · 2016-10-10T20:17:45Z

logging/quickstart.rb

+  # [END logging_quickstart]
+end
+
+if __FILE__ == $PROGRAM_NAME


Remove along with wrapper methods

1. Aligned group assignments 2. Removed cleanup from spec/quickstart_spec.rb 3. Fixed load call line 4. Removed "_test_client" and "_client" from variable names.

1. Removed comments from quickstart's RSpecs

1. removed "_client" from datastore quickstart.rb

1. Expanded spec to create and delete a new log_name for entries created during tests. 2. Removed unnecessary comments.

…ples into quickstarts Keeping it up to date :D

1. Updated sample_spec.rb to not expect a double-quote after Log message: 2. Increased timed delay in quickstart_spec.rb

…try fetch - logging.entries filter: was not working without additional order: option - simplify log name to "quickstart_log_#{Time.now.to_i}" - always try to delete log after spec runs, allowing for NotFound exceptions - refactor entry lookup into a helper method

Refactor Logging Quickstart spec and fix by adding order clause to entry fetch

beccasaurus

Some very small syntax changes requested. Otherwise looks great!

Remove one last instances of _client
Use snake_case and never camelCase
Don't use #! shabang

beccasaurus · 2016-10-20T19:17:22Z

language/quickstart.rb

+
+# Instantiates a client
+gcloud          = Google::Cloud.new project_id
+language_client = gcloud.language


language_client --> language

beccasaurus · 2016-10-20T19:17:53Z

language/spec/quickstart_spec.rb

@@ -0,0 +1,34 @@
+#!/usr/bin/ruby


Remove shabang line

beccasaurus · 2016-10-20T19:18:22Z

language/spec/quickstart_spec.rb

+describe "Language Quickstart" do
+
+  it "detect sentiment" do
+    gcloud_test_client = Google::Cloud.new ENV["GOOGLE_CLOUD_PROJECT"]


gcloud_test_client --> gloud

beccasaurus · 2016-10-20T19:20:09Z

speech/quickstart.rb

+speech = gcloud.speech
+
+# The name of the audio file to transcribe
+fileName = "./audio_files/audio.raw"


fileName --> file_name

beccasaurus · 2016-10-20T19:21:16Z

vision/quickstart.rb

+vision = gcloud.vision
+
+# The name of the image file to annotate
+fileName = "./images/cat.jpg"


fileName --> file_name

beccasaurus · 2016-10-20T19:22:51Z

vision/spec/quickstart_spec.rb

+
+describe "Vision Quickstart" do
+
+  it "label a cat image" do


This description doesn't flow like a proper sentence.

Maybe it "performs label detection on sample image file" ?

beccasaurus · 2016-10-20T23:01:59Z

quickstarts branch can be removed after docs are updated to point to latest 2016.10.20 release, which includes these new, stable Quickstart samples

/cc @jmdobry

jmdobry self-assigned this Sep 29, 2016

This was referenced Sep 29, 2016

Add new "quickstart" samples. GoogleCloudPlatform/php-docs-samples#174

Merged

Add new "quickstart" samples GoogleCloudPlatform/python-docs-samples#547

Merged

[DO NOT MERGE] Upgrade pubsub samples. GoogleCloudPlatform/python-docs-samples#543

Closed

Add "quickstart" samples.

97b97e9

jmdobry force-pushed the quickstarts branch from 4415a68 to 97b97e9 Compare October 4, 2016 18:31

jmdobry changed the title ~~[DO NOT MERGE] Add "quickstart" samples.~~ Add "quickstart" samples. Oct 4, 2016

Tweak Datastore quickstart sample.

beab134

jmdobry mentioned this pull request Oct 5, 2016

Add new "quickstart" samples. GoogleCloudPlatform/golang-samples#131

Merged

20 tasks

jmdobry changed the title ~~Add "quickstart" samples.~~ Add new "quickstart" samples. Oct 5, 2016

Tweak Datastore quickstart sample.

318d761

frankyn self-assigned this Oct 6, 2016

jmdobry and others added 3 commits October 6, 2016 15:01

Change datastore quickstart sample to create a task.

bb13651

Changes:

a44f362

1. Added test for BigQuery quickstart 2. Updated information about quickstart in README.md

Changes:

48b30fe

1. Removed unecessary space in bigquery quickstart spec

jmdobry mentioned this pull request Oct 7, 2016

Add google-cloud-java client libraries quickstart samples. GoogleCloudPlatform/java-docs-samples#353

Merged

12 tasks

Frank Natividad added 2 commits October 7, 2016 16:23

Changes:

4bcdf07

1. Updated quickstart.rb to be a global set of instructions 2. Updated spec/quickstart_spec.rb to be a minimal test. (There's only one function to test.)

Changes:

4f1b02c

1. Substituated single quotes for double quotes.

jmdobry commented Oct 7, 2016

View reviewed changes

Frank Natividad and others added 4 commits October 7, 2016 16:58

Changes:

e81e741

1. Added RSpec for quickstart.rb 2. Modified quickstart.rb to be a globally scopped.

Changes:

2590342

1. Added spec/quickstart.rb to test quickstart.rb 2. Changed quickstart.rb to be globally scoped.

Changes:

5e9c228

1. Fixed typo

Simplify print statement in Vision quickstart.

740c7cd

beccasaurus suggested changes Oct 10, 2016

View reviewed changes

Changes:

ca30bc2

1. Aligned group assignments 2. Removed cleanup from spec/quickstart_spec.rb 3. Fixed load call line 4. Removed "_test_client" and "_client" from variable names.

Frank Natividad and others added 17 commits October 11, 2016 16:42

Changes:

71a0f2f

1. Removed comments from quickstart's RSpecs

Changes:

c2994e0

1. removed "_client" from datastore quickstart.rb

Removed extra spaces in logging/quickstart.rb

73fdf64

Removed %Q{} and used single-quotes instead

97f366e

Removed spaces from assignment in trasnlate

3249d27

Removed multiple label lookup in Vision quickstart_spec.rb (using cat)!

e522da5

Added wait_until helper function and removed direct call to sleep

01cd1d8

Changes:

183ef4b

1. Expanded spec to create and delete a new log_name for entries created during tests. 2. Removed unnecessary comments.

Merge branch 'master' of github.com:GoogleCloudPlatform/ruby-docs-sam…

7b31107

…ples into quickstarts Keeping it up to date :D

Changes:

a450c94

1. Updated sample_spec.rb to not expect a double-quote after Log message: 2. Increased timed delay in quickstart_spec.rb

Modified expectation to attempt to fix Travis CI

4881ae7

Merge pull request #90 from GoogleCloudPlatform/logging-quickstart-spec

a06b18a

Refactor Logging Quickstart spec and fix by adding order clause to entry fetch

Removed some spacing found by Vim

c0586e7

Changed %{} to %Q{} to be more explicit.

73b620b

Removed order from filter. Using full project path

0a17905

Modified quickstart spec test to check poliarity

0e6e529

beccasaurus suggested changes Oct 20, 2016

View reviewed changes

Frank Natividad added 4 commits October 20, 2016 12:39

Language Removed _client, _test_client, and shabang line

b7eef07

Speech quickstart changed fileName -> file_name

3447327

Vision quickstart: changed fileName -> file_name

ff23358

Vision quickstart spec: added better description

64953d3

frankyn force-pushed the quickstarts branch from 35f1e12 to 64953d3 Compare October 20, 2016 19:50

Language/quickstart.rb Remove unwanted spacing.

5796925

beccasaurus approved these changes Oct 20, 2016

View reviewed changes

beccasaurus merged commit ca91692 into master Oct 20, 2016

beccasaurus deleted the quickstarts branch October 20, 2016 22:51

beccasaurus restored the quickstarts branch October 20, 2016 22:52

beccasaurus deleted the quickstarts branch February 7, 2017 21:34


		expect(bigquery_test_client.dataset "my_new_dataset").not_to be nil

		# Clean up


		### Quickstart

		'''

Comments

Conversation

jmdobry commented Sep 29, 2016 • edited by frankyn Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jmdobry commented Oct 4, 2016

Uh oh!

frankyn commented Oct 6, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

beccasaurus left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

beccasaurus commented Oct 20, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jmdobry commented Sep 29, 2016 •

edited by frankyn

Loading

frankyn commented Oct 6, 2016 •

edited

Loading