videointelligence: Harmonize / DRY 'README.rst' / 'docs/index.rst'. (#6002)

tseaver · web-flow · commit a4cfe84b3d80 · 2018-09-21T11:31:30.000-04:00
diff --git a/videointelligence/README.rst b/videointelligence/README.rst
@@ -1,48 +1,95 @@
 Python Client for Google Cloud Video Intelligence
 =================================================
 
-    Python idiomatic client for `Google Cloud Video Intelligence`_
+|pypi| |versions|
 
-.. _Google Cloud Video Intelligence: https://cloud.google.com/video-intelligence/
+`Google Cloud Video Intelligence`_ API makes videos searchable, and
+discoverable, by extracting metadata with an easy to use API.
+You can now search every moment of every video file in your catalog
+and find every occurrence as well as its significance. It quickly
+annotates videos stored in `Google Cloud Storage`_, and helps you
+identify key nouns entities of your video, and when they occur
+within the video. Separate signal from noise, by retrieving
+relevant information at the video, shot or per frame.
 
-|pypi| |versions|
+- `Client Library Documentation`_
+- `Product Documentation`_
+
+.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-videointelligence.svg
+   :target: https://pypi.org/project/google-cloud-videointelligence/
+.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-videointelligence.svg
+   :target: https://pypi.org/project/google-cloud-videointelligence/
+.. _Google Cloud Video Intelligence: https://cloud.google.com/video-intelligence/
+.. _Google Cloud Storage: https://cloud.google.com/storage/
+.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/datastore/index.html
+.. _Product Documentation: https://cloud.google.com/video-intelligence/docs/
 
 Quick Start
 -----------
 
-.. code-block:: console
+In order to use this library, you first need to go through the following steps:
 
-    $ pip install --upgrade google-cloud-videointelligence
+1. `Select or create a Cloud Platform project.`_
+2. `Enable billing for your project.`_
+3. `Enable the Google Cloud Video Intelligence API.`_
+4. `Setup Authentication.`_
 
-For more information on setting up your Python development environment,
-such as installing ``pip`` and ``virtualenv`` on your system, please refer
-to `Python Development Environment Setup Guide`_ for Google Cloud Platform.
+.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
+.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
+.. _Enable the Google Cloud Video Intelligence API.:  https://cloud.google.com/datastore
+.. _Setup Authentication.: https://googlecloudplatform.github.io/google-cloud-python/latest/core/auth.html
 
-.. _Python Development Environment Setup Guide: https://cloud.google.com/python/setup
+Installation
+~~~~~~~~~~~~
 
-Authentication
---------------
+Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
+create isolated Python environments. The basic problem it addresses is one of
+dependencies and versions, and indirectly permissions.
 
-With ``google-cloud-python`` we try to make authentication as painless as
-possible. Check out the `Authentication section`_ in our documentation to
-learn more. You may also find the `authentication document`_ shared by all
-the ``google-cloud-*`` libraries to be helpful.
+With `virtualenv`_, it's possible to install this library without needing system
+install permissions, and without clashing with the installed system
+dependencies.
 
-.. _Authentication section: https://google-cloud-python.readthedocs.io/en/latest/core/auth.html
-.. _authentication document: https://github.com/GoogleCloudPlatform/google-cloud-common/tree/master/authentication
+.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
 
-Using the API
--------------
+Mac/Linux
+^^^^^^^^^
 
-The Google Cloud `Video Intelligence`_ (`Video Intelligence API docs`_)
-API enables developers to
-understand the content of a video by encapsulating powerful machine
-learning models in an easy to use REST API.
+.. code-block:: console
 
-.. _Video Intelligence: https://cloud.google.com/video-intelligence/
-.. _Video Intelligence API docs: https://cloud.google.com/video-intelligence/docs/reference/rest/
+    pip install virtualenv
+    virtualenv <your-env>
+    source <your-env>/bin/activate
+    <your-env>/bin/pip install google-cloud-datastore
 
-.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-videointelligence.svg
-   :target: https://pypi.org/project/google-cloud-videointelligence/
-.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-videointelligence.svg
-   :target: https://pypi.org/project/google-cloud-videointelligence/
+Windows
+^^^^^^^
+
+.. code-block:: console
+
+    pip install virtualenv
+    virtualenv <your-env>
+    <your-env>\Scripts\activate
+    <your-env>\Scripts\pip.exe install google-cloud-datastore
+
+Example Usage
+~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   from google.cloud import videointelligence
+   
+   client = videointelligence.VideoIntelligenceServiceClient()
+   job = client.annotate_video(
+       input_uri='gs://<bucket-name>/my_video.mp4',
+       features=['LABEL_DETECTION', 'SHOT_CHANGE_DETECTION'],
+   )
+   result = job.result()
+
+Next Steps
+~~~~~~~~~~
+
+-  Read the `Client Library Documentation`_ for Google Cloud Video Intelligence 
+   API to see other available methods on the client.
+-  Read the `Product documentation`_ to learn
+   more about the product and see How-to Guides.
diff --git a/videointelligence/docs/index.rst b/videointelligence/docs/index.rst
@@ -1,87 +1,7 @@
-Video Intelligence
-==================
+.. include:: /../videointelligence/README.rst
 
-`Google Cloud Video Intelligence`_ API makes videos searchable, and
-discoverable, by extracting metadata with an easy to use API.
-You can now search every moment of every video file in your catalog
-and find every occurrence as well as its significance. It quickly
-annotates videos stored in `Google Cloud Storage`_, and helps you
-identify key nouns entities of your video, and when they occur
-within the video. Separate signal from noise, by retrieving
-relevant information at the video, shot or per frame.
-
-.. _Google Cloud Video Intelligence: https://cloud.google.com/video-intelligence/
-.. _Google Cloud Storage: https://cloud.google.com/storage/
-
-************
-Installation
-************
-
-Install the ``google-cloud-videointelligence`` library using ``pip``:
-
-.. code-block:: console
-
-    $ pip install google-cloud-videointelligence
-
-
-********************************
-Authentication and Configuration
-********************************
-
-- For an overview of authentication in ``google-cloud-python``,
-  see :doc:`/core/auth`.
-
-- In addition to any authentication configuration, you should also set the
-  :envvar:`GOOGLE_CLOUD_PROJECT` environment variable for the project you'd
-  like to interact with. If the :envvar:`GOOGLE_CLOUD_PROJECT` environment
-  variable is not present, the project ID from JSON file credentials is used.
-
-  If you are using Google App Engine or Google Compute Engine
-  this will be detected automatically.
-
-- After configuring your environment, create a
-  :class:`~google.cloud.videointelligence_v1.VideoIntelligenceServiceClient`.
-
-.. code-block:: python
-
-     >>> from google.cloud import videointelligence
-     >>> client = videointelligence.VideoIntelligenceServiceClient()
-
-or pass in ``credentials`` explicitly.
-
-.. code-block:: python
-
-     >>> from google.cloud import videointelligence
-     >>> client = videointelligence.VideoIntelligenceServiceClient(
-     ...     credentials=creds,
-     ... )
-
-
-******************
-Annotating a Video
-******************
-
-To annotate a video, just determine which annotation features you want, and point
-the API at your video:
-
-.. code-block:: python
-
-    >>> from google.cloud import videointelligence
-    >>>
-    >>> client = videointelligence.VideoIntelligenceServiceClient()
-    >>> result = client.annotate_video(
-    ...     input_uri='gs://cloudmleap/video/next/animals.mp4',
-    ...     features=['LABEL_DETECTION', 'SHOT_CHANGE_DETECTION'],
-    ... ).result()
-    >>> result.annotationResults[0].labelAnnotations[0].description
-    'Android'
-    >>> result.annotationResults[0].labelAnnotations[1].description
-    'Animation'
-
-
-*************
 API Reference
-*************
+-------------
 
 
 This package includes clients for multiple versions of the Video Intelligence
@@ -124,6 +44,10 @@ An API and type reference is provided the these betas also:
     gapic/v1beta2/api
     gapic/v1beta2/types
 
+
+Changelog
+---------
+
 For a list of all ``google-cloud-videointelligence`` releases:
 
 .. toctree::
