From 64f5f57d39f22239a81f7cf4c35be214baf4ed13 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Mon, 17 Sep 2018 16:52:19 -0400 Subject: [PATCH] Harmonize / DRY VI 'README.rst' / 'docs/index.rst'. --- videointelligence/README.rst | 105 ++++++++++++++++++++++--------- videointelligence/docs/index.rst | 88 ++------------------------ 2 files changed, 82 insertions(+), 111 deletions(-) diff --git a/videointelligence/README.rst b/videointelligence/README.rst index 70a5cc5937bf..f9e5ca7b02cd 100644 --- 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 + source /bin/activate + /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 + \Scripts\activate + \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:///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 index 1a37c9409e3d..bdf5727d99d5 100644 --- 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 @@ -121,6 +41,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::