Initial Vision usage docs for discussion

[daspecster]

Here is a rough outline of the Vision usage RST.

Originally mentioned here.

The usage here essentially implies direct conversion of the responses to objects.
I think we have room here to add helper methods which could add value.

Let's discuss!

[theacodes]

/cc @jerjou

[jgeewax]

Can you take a look at our Vision docs for Ruby that do things slightly differently? https://quartzmo.github.io/gcloud-ruby/#/docs/master/gcloud/vision

[daspecster]

@jgeewax I like their examples!

Are you saying to look at their docs as an example for the usage layout or for how their API is defined...or both I suppose?

I can condense this down a bit. I wanted to layout the cases here so we could discuss the API surface.

[quartzmo]

@jgeewax @daspecster I'm working on updating our Vision docs demo with googleapis/google-cloud-ruby#696 and another pending PR, just FYI.

[daspecster]

One thing that I'm not sure about in gcloud-ruby is that the way they do the multiple images example. I think it actually would cost more since there would be multiple API requests?

However I guess since the charging is based on the feature types that in their example it wouldn't make any difference?

analyses = vision.annotate do |annotate|
   annotate.annotate face_image, faces: 10, labels: 10
   annotate.annotate landmark_image, landmarks: 10
   annotate.annotate text_image, text: true
end

In that case I guess the only part in question is request overhead. I think the batching discussion will get there though.

[quartzmo]

We have changed our API to accept booleans as well as max results, so when updated, most examples will use this new syntax:

annotation = vision.annotate image, faces: true, labels: true

[daspecster]

@quartzmo, I like changing the max_results to true, since with some feature types rarely if ever would more than one result be returned.

I could take that out here and just make the default max_results=1 and then not that in the docs but leave it out of most of the examples.

[quartzmo]

@daspecster The batch example you mention above results in a single API request. Nothing happens until the block execution completes.

[daspecster]

@quartzmo, I see now. Thanks!

[quartzmo]

@daspecster We released our Vision support today in case you want to try it.

[daspecster]

@quartzmo thanks! I'll give it a go this weekend.

[dhermes]

General comment: Though there is only one method provided by the backend API, we can and should have many methods in our API, matching the concepts at the level you provide in each docs subsection.

[daspecster]

@dhermes @tseaver, the doc was updated with convenience methods like detect_labels() etc.
Not sure why it days they were added 9 days ago though? I pushed it on one of those github outage days.

If you guys want to take a look at it again and let me know what you think that would be awesome!

[daspecster]

@dhermes @tseaver, just wanted to try and keep this alive. Let me know if you have any comments! If not then I'll start working on implementing this Thursday(June 2nd).

Thanks!

[tseaver]

LGTM to go forward with the surface as described.

[daspecster]

Closing since we shouldn't have a usage doc with no surface methods available yet.

Reopen if we want to chat more about any of this!

[daspecster]

/cc @jgeewax