Merge docs into master. (#11)

packages/google-cloud-dialogflow/.circleci/config.yml

@@ -137,9 +137,12 @@ jobs:
       - image: python:3.6
     steps:
       - checkout
+      - run:
+          name: Install nox.
+          command: pip install nox-automation
       - run:
           name: Build documentation.
-          command: echo "nox -s docs"
+          command: nox -s docs
 
   sample_tests:
     docker:

packages/google-cloud-dialogflow/README.rst

@@ -19,11 +19,9 @@ Google APIs Client Libraries, in
 
 .. _Dialogflow: https://dialogflow.com/
 
-Quickstart
-----------
 
 Before you begin
-~~~~~~~~~~~~~~~~
+----------------
 
 #. Select or create a Cloud Platform `project`_.
 #. `Enable billing`_ for your project.
@@ -38,7 +36,7 @@ Before you begin
 
 
 Installation
-~~~~~~~~~~~~
+------------
 
 .. code-block:: shell
 
@@ -51,7 +49,7 @@ Installation
 
 
 Versioning
-~~~~~~~~~~
+----------
 
 This library follows `Semantic Versioning <http://semver.org/>`_.
 
@@ -63,12 +61,12 @@ against beta libraries with a high priority.
 More Information: `Google Cloud Platform Launch Stages <https://cloud.google.com/terms/launch-stages>`_
 
 Contributing
-~~~~~~~~~~~~
+------------
 
 Contributions welcome! See the `Contributing Guide <https://github.com/googleapis/python-dialogflow/blob/master/.github/CONTRIBUTING.rst>`_.
 
 License
-~~~~~~~
+-------
 
 Apache Version 2.0
 

packages/google-cloud-dialogflow/dialogflow_v2beta1/gapic/agents_client.py

@@ -49,8 +49,8 @@ class AgentsClient(object):
     Manages conversational agents.
 
 
-    Refer to `documentation <https://dialogflow.com/docs/agents>`_ for more details
-    # about agents.
+    Refer to `agents documentation <https://dialogflow.com/docs/agents>`_ for
+    more details about agents.
 
     Standard methods.
     """

packages/google-cloud-dialogflow/dialogflow_v2beta1/gapic/contexts_client.py

@@ -48,8 +48,8 @@ class ContextsClient(object):
     Manages contexts.
 
 
-    Refer to `documentation <https://dialogflow.com/docs/contexts>`_ for more
-    # details about contexts.
+    Refer to `contexts documentation <https://dialogflow.com/docs/contexts>`_
+    for more details about contexts.
 
     Standard methods.
     """

packages/google-cloud-dialogflow/dialogflow_v2beta1/gapic/entity_types_client.py

@@ -52,8 +52,8 @@ class EntityTypesClient(object):
     Manages agent entity types.
 
 
-    Refer to `documentation <https://dialogflow.com/docs/entities>`_ for more
-    # details about entity types.
+    Refer to `entities documentation <https://dialogflow.com/docs/entities>`_
+    for more details about entity types.
 
     Standard methods.
     """

packages/google-cloud-dialogflow/dialogflow_v2beta1/gapic/intents_client.py

@@ -53,8 +53,8 @@ class IntentsClient(object):
     Manages agent intents.
 
 
-    Refer to `documentation <https://dialogflow.com/docs/intents>`_ for more
-    # details about agent intents.
+    Refer to `intents documentation <https://dialogflow.com/docs/intents>`_ for
+    more details about agent intents.
 
     Standard methods.
     """

packages/google-cloud-dialogflow/docs/gapic/v2beta1/api.rst

@@ -1,6 +1,6 @@
 Client for Dialogflow API
 =========================
 
-.. automodule:: google.cloud.dialogflow_v2beta1
+.. automodule:: dialogflow_v2beta1
     :members:
-    :inherited-members:
+    :inherited-members:

packages/google-cloud-dialogflow/docs/gapic/v2beta1/types.rst

@@ -1,5 +1,5 @@
 Types for Dialogflow API Client
 ===============================
 
-.. automodule:: google.cloud.dialogflow_v2beta1.types
-    :members:
+.. automodule:: dialogflow_v2beta1.types
+    :members:

packages/google-cloud-dialogflow/docs/index.rst

@@ -1,78 +1,183 @@
-Python Client for Dialogflow API (`Beta`_)
-===========================================
+Dialogflow: Python Client
+=========================
 
-`Dialogflow API`_: Dialogflow is an enterprise-grade NLU platform that makes it easy for
-developers to design and integrate conversational user interfaces into
+|release level| |circleci| |codecov|
+
+    Python idiomatic client for `Dialogflow`_
+
+`Dialogflow`_ is an enterprise-grade NLU platform that makes it easy for
+developers to design and integrate conversational user interfaces int
 mobile apps, web applications, devices, and bots.
 
-- `Client Library Documentation`_
-- `Product Documentation`_
+* `Dialogflow Enterprise Python Client API Reference <https://cloud.google.com/dialogflow-enterprise>`_
+* `Dialogflow Standard Edition Documentation <https://www.dialogflow.com>`_
+* `Dialogflow Enterprise Edition Documentation <https://cloud.google.com/dialogflow-enterprise/docs>`_
+
+Read more about the client libraries for Cloud APIs, including the older
+Google APIs Client Libraries, in
+`Client Libraries Explained <https://cloud.google.com/apis/docs/client-libraries-explained>`_.
 
-.. _Beta: https://github.com/GoogleCloudPlatform/google-cloud-python/blob/master/README.rst
-.. _Dialogflow API: https://cloud.google.com/dialogflow
-.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/stable/dialogflow-usage
-.. _Product Documentation:  https://cloud.google.com/dialogflow
+.. _Dialogflow: https://dialogflow.com/
 
-Quick Start
------------
 
-In order to use this library, you first need to go through the following steps:
+Before you begin
+----------------
 
-1. `Select or create a Cloud Platform project.`_
-2. `Enable the Dialogflow API.`_
-3. `Setup Authentication.`_
+#. Select or create a Cloud Platform `project`_.
+#. `Enable billing`_ for your project.
+#.  `Enable the Google Cloud Dialogflow API`_.
+#.  `Set up authentication`_ with a service account so you can access the
+    API from your local workstation.
+
+.. _project: https://console.cloud.google.com/project
+.. _Enable billing: https://support.google.com/cloud/answer/6293499#enable-billing
+.. _Enable the Google Cloud Dialogflow API: https://console.cloud.google.com/flows/enableapi?apiid=dialogflow.googleapis.com
+.. _Set up authentication: https://cloud.google.com/docs/authentication/getting-started
 
-.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
-.. _Enable the Dialogflow API.:  https://cloud.google.com/dialogflow
-.. _Setup Authentication.: https://googlecloudplatform.github.io/google-cloud-python/stable/google-cloud-auth
 
 Installation
-~~~~~~~~~~~~
+------------
+
+.. code-block:: shell
+
+    pip install dialogflow
+
+.. note::
+
+    We highly recommend that you install this library in a
+    `virtualenv <https://virtualenv.pypa.io/en/latest/>`_.
+
+
+Using Dialogflow
+----------------
+
+Importing the Library
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    import dialogflow
+
+Detecting Intent (Texts)
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use the Dialogflow API to detect the intent from texts:
+
+.. literalinclude:: ../samples/detect_intent_texts.py
+    :start-after: # [START dialogflow_detect_intent_text]
+    :end-before: # [END dialogflow_detect_intent_text]
+
+Detecting Intent (Audio)
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use the Dialogflow API to detect the intent of a speaker given an
+audio file:
+
+.. literalinclude:: ../samples/detect_intent_audio.py
+    :start-after: # [START dialogflow_detect_intent_audio]
+    :end-before: # [END dialogflow_detect_intent_audio]
+
+Detecting Intent (Streaming Audio)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use the Dialogflow API to detect the intent of a speaker given a
+stream of audio:
+
+.. literalinclude:: ../samples/detect_intent_stream.py
+    :start-after: # [START dialogflow_detect_intent_streaming]
+    :end-before: # [END dialogflow_detect_intent_streaming]
+
+Managing Intents
+~~~~~~~~~~~~~~~~
+
+You can use the Dialogflow API to create intents:
+
+.. literalinclude:: ../samples/intent_management.py
+    :start-after: # [START dialogflow_create_intent]
+    :end-before: # [END dialogflow_create_intent]
+
+To delete intents:
+
+.. literalinclude:: ../samples/intent_management.py
+    :start-after: # [START dialogflow_delete_intent]
+    :end-before: # [END dialogflow_delete_intent]
+
+Managing Entity Types
+~~~~~~~~~~~~~~~~~~~~~
+
+You can use the Dialogflow API to create entity types:
+
+.. literalinclude:: ../samples/entity_type_management.py
+    :start-after: # [START dialogflow_create_entity_type]
+    :end-before: # [END dialogflow_create_entity_type]
+
+To delete entity types:
+
+.. literalinclude:: ../samples/entity_type_management.py
+    :start-after: # [START dialogflow_delete_entity_type]
+    :end-before: # [END dialogflow_delete_entity_type]
+
+Managing Entities
+~~~~~~~~~~~~~~~~~
+
+You can use the Dialogflow API to create entities:
+
+.. literalinclude:: ../samples/entity_management.py
+    :start-after: # [START dialogflow_create_entity]
+    :end-before: # [END dialogflow_create_entity]
+
+To delete entities:
+
+.. literalinclude:: ../samples/entity_management.py
+    :start-after: # [START dialogflow_delete_entity]
+    :end-before: # [END dialogflow_delete_entity]
+
+Managing Session Entity Types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use the Dialogflow API to create session entity types:
 
-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.
+.. literalinclude:: ../samples/session_entity_type_management.py
+    :start-after: # [START dialogflow_create_session_entity_type]
+    :end-before: # [END dialogflow_create_session_entity_type]
 
-With `virtualenv`_, it's possible to install this library without needing system
-install permissions, and without clashing with the installed system
-dependencies.
+To delete session entity types:
 
-.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
+.. literalinclude:: ../samples/session_entity_type_management.py
+    :start-after: # [START dialogflow_delete_session_entity_type]
+    :end-before: # [END dialogflow_delete_session_entity_type]
 
+Versioning
+----------
 
-Mac/Linux
-^^^^^^^^^
+This library follows `Semantic Versioning <http://semver.org/>`_.
 
-.. code-block:: console
+This library is considered to be in **beta**. This means it is expected to be
+mostly stable while we work toward a general availability release; however,
+complete stability is not guaranteed. We will address issues and requests
+against beta libraries with a high priority.
 
-    pip install virtualenv
-    virtualenv <your-env>
-    source <your-env>/bin/activate
-    <your-env>/bin/pip install dialogflow
+More Information: `Google Cloud Platform Launch Stages <https://cloud.google.com/terms/launch-stages>`_
 
+Contributing
+------------
 
-Windows
-^^^^^^^
+Contributions welcome! See the `Contributing Guide <https://github.com/googleapis/python-dialogflow/blob/master/.github/CONTRIBUTING.rst>`_.
 
-.. code-block:: console
+License
+-------
 
-    pip install virtualenv
-    virtualenv <your-env>
-    <your-env>\Scripts\activate
-    <your-env>\Scripts\pip.exe install dialogflow
+Apache Version 2.0
 
-Next Steps
-~~~~~~~~~~
+See `the LICENSE file <https://github.com/googleapis/python-dialogflow/blob/master/LICENSE>`_ for more information.
 
--  Read the `Client Library Documentation`_ for Dialogflow API
-   API to see other available methods on the client.
--  Read the `Dialogflow API Product documentation`_ to learn
-   more about the product and see How-to Guides.
--  View this `repository’s main README`_ to see the full list of Cloud
-   APIs that we cover.
 
-.. _Dialogflow API Product documentation:  https://cloud.google.com/dialogflow
-.. _repository’s main README: https://github.com/GoogleCloudPlatform/google-cloud-python/blob/master/README.rst
+.. |release level| image:: https://img.shields.io/badge/release%20level-beta-yellow.svg?style&#x3D;flat
+    :target: https://cloud.google.com/terms/launch-stages
+.. |circleci| image:: https://img.shields.io/circleci/project/github/dialogflow/dialogflow-python-client-v2.svg?style=flat)
+    :target: https://circleci.com/gh/dialogflow/dialogflow-python-client-v2
+.. |codecov| image:: https://img.shields.io/codecov/c/github/dialogflow/dialogflow-python-client-v2/master.svg?style=flat)
+    :target: https://codecov.io/gh/dialogflow/dialogflow-python-client-v2
 
 Api Reference
 -------------

packages/google-cloud-dialogflow/nox.py

@@ -58,6 +58,19 @@ def lint_setup_py(session):
                 '--strict')
 
 
+@nox.session
+def docs(session):
+    """Build the docs."""
+
+    session.install('sphinx', 'sphinx_rtd_theme')
+    session.install('.')
+
+    # Build the docs!
+    session.run('rm', '-rf', 'docs/_build/')
+    session.run('sphinx-build', '-W', '-b', 'html', '-d',
+                'docs/_build/doctrees', 'docs/', 'docs/_build/html/')
+
+
 @nox.session
 def cover(session):
     """Run the final coverage report.