Skip to content

Commit bc741d0

Browse files
tseavertseaver
authored
Vision: Harmonize / DRY 'README.rst' / 'docs/index.rst'. (#6003)
1 parent a4cfe84 commit bc741d0

File tree

2 files changed

+86
-108
lines changed

2 files changed

+86
-108
lines changed

‎vision/README.rst‎

Lines changed: 78 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,101 @@
11
Python Client for Google Cloud Vision
22
=====================================
33

4-
Python idiomatic client for `Google Cloud Vision`_
4+
|pypi| |versions|
55

6-
.. _Google Cloud Vision: https://cloud.google.com/vision/
6+
The `Google Cloud Vision`_ API enables developers to
7+
understand the content of an image by encapsulating powerful machine
8+
learning models in an easy to use REST API. It quickly classifies images
9+
into thousands of categories (e.g., "sailboat", "lion", "Eiffel Tower"),
10+
detects individual objects and faces within images, and finds and reads
11+
printed words contained within images. You can build metadata on your
12+
image catalog, moderate offensive content, or enable new marketing
13+
scenarios through image sentiment analysis. Analyze images uploaded
14+
in the request or integrate with your image storage on Google Cloud
15+
Storage.
716

8-
|pypi| |versions|
17+
- `Client Library Documentation`_
18+
- `Product Documentation`_
919

10-
- `Documentation`_
20+
.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-vision.svg
21+
:target: https://pypi.org/project/google-cloud-vision/
22+
.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-vision.svg
23+
:target: https://pypi.org/project/google-cloud-vision/
24+
.. _Vision: https://cloud.google.com/vision/
25+
26+
.. _Google Cloud Vision: https://cloud.google.com/vision/
27+
.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/vision/
28+
.. _Product Documentation: https://cloud.google.com/vision/reference/rest/
1129

12-
.. _Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/vision/
1330

1431
Quick Start
1532
-----------
1633

34+
In order to use this library, you first need to go through the following steps:
35+
36+
1. `Select or create a Cloud Platform project.`_
37+
2. `Enable billing for your project.`_
38+
3. `Enable the Google Cloud Vision API.`_
39+
4. `Setup Authentication.`_
40+
41+
.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
42+
.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
43+
.. _Enable the Google Cloud Vision API.: https://cloud.google.com/vision
44+
.. _Setup Authentication.: https://googlecloudplatform.github.io/google-cloud-python/latest/core/auth.html
45+
46+
Installation
47+
~~~~~~~~~~~~
48+
49+
Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
50+
create isolated Python environments. The basic problem it addresses is one of
51+
dependencies and versions, and indirectly permissions.
52+
53+
With `virtualenv`_, it's possible to install this library without needing system
54+
install permissions, and without clashing with the installed system
55+
dependencies.
56+
57+
.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
58+
59+
60+
Mac/Linux
61+
^^^^^^^^^
62+
1763
.. code-block:: console
1864
19-
$ pip install --upgrade google-cloud-vision
65+
pip install virtualenv
66+
virtualenv <your-env>
67+
source <your-env>/bin/activate
68+
<your-env>/bin/pip install google-cloud-vision
2069
21-
For more information on setting up your Python development environment,
22-
such as installing ``pip`` and ``virtualenv`` on your system, please refer
23-
to `Python Development Environment Setup Guide`_ for Google Cloud Platform.
2470
25-
.. _Python Development Environment Setup Guide: https://cloud.google.com/python/setup
71+
Windows
72+
^^^^^^^
2673

27-
Authentication
28-
--------------
74+
.. code-block:: console
2975
30-
With ``google-cloud-python`` we try to make authentication as painless as
31-
possible. Check out the `Authentication section`_ in our documentation to
32-
learn more. You may also find the `authentication document`_ shared by all
33-
the ``google-cloud-*`` libraries to be helpful.
76+
pip install virtualenv
77+
virtualenv <your-env>
78+
<your-env>\Scripts\activate
79+
<your-env>\Scripts\pip.exe install google-cloud-vision
3480
35-
.. _Authentication section: https://google-cloud-python.readthedocs.io/en/latest/core/auth.html
36-
.. _authentication document: https://github.com/GoogleCloudPlatform/google-cloud-common/tree/master/authentication
3781
38-
Using the API
39-
-------------
82+
Example Usage
83+
~~~~~~~~~~~~~
4084

41-
The Google Cloud `Vision`_ (`Vision API docs`_) API enables developers to
42-
understand the content of an image by encapsulating powerful machine
43-
learning models in an easy to use REST API. It quickly classifies images
44-
into thousands of categories (e.g., "sailboat", "lion", "Eiffel Tower"),
45-
detects individual objects and faces within images, and finds and reads
46-
printed words contained within images. You can build metadata on your
47-
image catalog, moderate offensive content, or enable new marketing
48-
scenarios through image sentiment analysis. Analyze images uploaded
49-
in the request or integrate with your image storage on Google Cloud
50-
Storage.
85+
.. code-block:: python
5186
52-
.. _Vision: https://cloud.google.com/vision/
53-
.. _Vision API docs: https://cloud.google.com/vision/reference/rest/
87+
from google.cloud import vision
5488
55-
See the ``google-cloud-python`` API `Documentation`_ to learn
56-
how to analyze images using this library.
89+
client = vision.ImageAnnotatorClient()
90+
response = client.annotate_image({
91+
'image': {'source': {'image_uri': 'gs://my-test-bucket/image.jpg'}},
92+
'features': [{'type': vision.enums.Feature.Type.FACE_DETECTION}],
93+
})
5794
58-
.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-vision.svg
59-
:target: https://pypi.org/project/google-cloud-vision/
60-
.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-vision.svg
61-
:target: https://pypi.org/project/google-cloud-vision/
95+
Next Steps
96+
~~~~~~~~~~
97+
98+
- Read the `Client Library Documentation`_ for Google Cloud Vision API
99+
API to see other available methods on the client.
100+
- Read the `Product documentation`_ to learn
101+
more about the product and see How-to Guides.

‎vision/docs/index.rst‎

Lines changed: 8 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,68 +1,10 @@
1-
######
2-
Vision
3-
######
1+
.. include:: /../vision/README.rst
42

5-
The Google Cloud `Vision`_ (`Vision API docs`_) API enables developers to
6-
understand the content of an image by encapsulating powerful machine
7-
learning models in an easy to use REST API. It quickly classifies images
8-
into thousands of categories (e.g., "sailboat", "lion", "Eiffel Tower"),
9-
detects individual objects and faces within images, and finds and reads
10-
printed words contained within images. You can build metadata on your
11-
image catalog, moderate offensive content, or enable new marketing
12-
scenarios through image sentiment analysis. Analyze images uploaded
13-
in the request or integrate with your image storage on Google Cloud
14-
Storage.
3+
Using the Library
4+
-----------------
155

16-
.. _Vision: https://cloud.google.com/vision/
17-
.. _Vision API docs: https://cloud.google.com/vision/reference/rest/
18-
19-
************
20-
Installation
21-
************
22-
23-
Install the ``google-cloud-vision`` library using ``pip``:
24-
25-
.. code-block:: console
26-
27-
$ pip install google-cloud-vision
28-
29-
30-
********************************
31-
Authentication and Configuration
32-
********************************
33-
34-
- For an overview of authentication in ``google-cloud-python``,
35-
see :doc:`/core/auth`.
36-
37-
- In addition to any authentication configuration, you should also set the
38-
:envvar:`GOOGLE_CLOUD_PROJECT` environment variable for the project you'd
39-
like to interact with. If the :envvar:`GOOGLE_CLOUD_PROJECT` environment
40-
variable is not present, the project ID from JSON file credentials is used.
41-
42-
If you are using Google App Engine or Google Compute Engine
43-
this will be detected automatically.
44-
45-
- After configuring your environment, create a
46-
:class:`~google.cloud.vision_v1.ImageAnnotatorClient`.
47-
48-
.. code-block:: python
49-
50-
>>> from google.cloud import vision
51-
>>> client = vision.ImageAnnotatorClient()
52-
53-
or pass in ``credentials`` explicitly.
54-
55-
.. code-block:: python
56-
57-
>>> from google.cloud import vision
58-
>>> client = vision.ImageAnnotatorClient(
59-
... credentials=creds,
60-
... )
61-
62-
63-
*****************
646
Annotate an Image
65-
*****************
7+
~~~~~~~~~~~~~~~~~
668

679
You can call the :meth:`annotate_image` method directly:
6810

@@ -87,9 +29,8 @@ You can call the :meth:`annotate_image` method directly:
8729
'github'
8830
8931
90-
************************
9132
Single-feature Shortcuts
92-
************************
33+
~~~~~~~~~~~~~~~~~~~~~~~~
9334

9435
If you are only requesting a single feature, you may find it easier to ask
9536
for it using our direct methods:
@@ -110,9 +51,8 @@ for it using our direct methods:
11051
Likelihood.VERY_LIKELY
11152
11253
113-
****************
11454
No results found
115-
****************
55+
~~~~~~~~~~~~~~~~
11656

11757
If no results for the detection performed can be extracted from the image, then
11858
an empty list is returned. This behavior is similar with all detection types.
@@ -132,9 +72,8 @@ Example with :meth:`~google.cloud.vision.ImageAnnotatorClient.logo_detection`:
13272
>>> len(response.annotations)
13373
0
13474
135-
*************
13675
API Reference
137-
*************
76+
-------------
13877

13978
This package includes clients for multiple versions of the Vision
14079
API. By default, you will get ``v1``, the latest stable version.
@@ -169,9 +108,8 @@ An API and type reference is provided for this beta:
169108
gapic/v1p2beta1/api
170109
gapic/v1p2beta1/types
171110

172-
*********
173111
Changelog
174-
*********
112+
---------
175113

176114
For a list of all ``google-cloud-vision`` releases:
177115

0 commit comments

Comments
 (0)