samples: tweak samples to use kwarg syntax, update guide

UPGRADING.md

@@ -1,58 +1,134 @@
+# 2.0.0 Migration Guide
 
+The 2.0.0 release of `google-cloud-texttospeech` is based on a [new code generator](https://github.com/googleapis/gapic-generator-python) and has significant differences from the previous major release. This guide explains how to modify your code to be compatible with the latest major version of the library.
 
-<!-- WIP, to be moved to google-cloud-python repository --->
+If you experience issues or have questions, please file an [issue](https://github.com/googleapis/python-texttospeech/issues).
 
-# Method Calls
+## Supported Python Versions
 
-Methods now expect request objects. We provide a script that will convert most common cases automatically. 
+> **WARNING**: Breaking change
 
-1. Install the library
+The 2.0.0 release requires Python 3.6+.
+
+
+## Method Calls
+
+> **WARNING**: Breaking change
+
+Methods expect request objects. We provide a script that will convert most common use cases.
+
+* Install the library
 
 ```py
 python3 -m pip install google-cloud-text-to-speech
 ```
 
-2. `fixup_keywords.py` is shipped with the library. The script expects
+* The script `fixup_keywords.py` is shipped with the library. It expects
 an input directory (with the code to convert) and an empty destination directory.
 
 ```sh
 $ fixup_keywords.py --input-directory .samples/ --output-directory samples/
 ```
 
-Before:
+**Before:**
 ```py
 from google.cloud import texttospeech
 
 client = texttospeech.TextToSpeechClient()
+
 voices = client.list_voices(language_code="no")
 ```
 
-After:
+
+**After:**
 ```py
 from google.cloud import texttospeech
 
 client = texttospeech.TextToSpeechClient()
+
 voices = client.list_voices(request={"language_code": "no"})
 ```
 
-# Location of Types and Enums
+### More Details
+
+In `google-cloud-texttospeech<2.0.0`, arguments required by the API were positional arguments and optional arguments were keyword arguments.
+
+**Before:**
+```py
+    def synthesize_speech(
+        self,
+        input_,
+        voice,
+        audio_config,
+        retry=google.api_core.gapic_v1.method.DEFAULT,
+        timeout=google.api_core.gapic_v1.method.DEFAULT,
+        metadata=None,
+    ):
+```
+
+In the 2.0.0 release, all methods have a single positional argument `request`.
+
+Some methods have additional keyword only arguments. The available parameters depend on the [`google.api.method_signature` annotation](https://github.com/googleapis/googleapis/blob/master/google/cloud/texttospeech/v1/cloud_tts.proto#L53) specified by the API producer.
 
-Types and Enums are available at the top level.
 
-Before:
+
+**After:**
+```py
+    def synthesize_speech(
+        self,
+        request: cloud_tts.SynthesizeSpeechRequest = None,
+        *,
+        input: cloud_tts.SynthesisInput = None,
+        voice: cloud_tts.VoiceSelectionParams = None,
+        audio_config: cloud_tts.AudioConfig = None,
+        retry: retries.Retry = gapic_v1.method.DEFAULT,
+        timeout: float = None,
+        metadata: Sequence[Tuple[str, str]] = (),
+    ) -> cloud_tts.SynthesizeSpeechResponse:
+```
+
+For this method, both of these calls are valid:
+
+```py
+response = client.synthesize_speech(
+    request={
+        "input": input_text,
+        "voice": voice,
+        "audio_config": audio_config
+    }
+)
+```
+
+```py
+response = client.synthesize_speech(
+    input=input_text,
+    voice=voice,
+    audio_config=audio_config
+)
+```
+
+
+## Enums and Types
+
+
+> **WARNING**: Breaking change
+
+The submodules `enums` and `types` have been removed.
+
+**Before:**
 ```py
 
 from google.cloud import texttospeech
 
-voice = texttospeech.types.VoiceSelectionParams(language_code="en-US")
 encoding = texttospeech.enums.AudioEncoding.MP3
+voice = texttospeech.types.VoiceSelectionParams(language_code="en-US")
 ```
 
 
-After:
+**After:**
 ```py
 from google.cloud import texttospeech
 
-voice = texttospeech.VoiceSelectionParams(language_code="en-US")
 encoding = texttospeech.AudioEncoding.MP3
-```
+voice = texttospeech.VoiceSelectionParams(language_code="en-US")
+```

docs/UPGRADING.md

@@ -0,0 +1 @@
+../UPGRADING.md

docs/index.rst

@@ -27,6 +27,18 @@ v1beta1 API Reference
     Client (v1beta1) <texttospeech_v1beta1/services>
     Types (v1beta1) <texttospeech_v1beta1/types>
 
+
+Migration Guide
+---------------
+
+See the guide below for instructions on migrating to the 2.x release of this library.
+
+.. toctree::
+    :maxdepth: 2
+
+    UPGRADING
+
+
 Changelog
 ---------
 

samples/snippets/audio_profile.py

@@ -45,7 +45,7 @@ def synthesize_text_with_audio_profile(text, output, effects_profile_id):
         effects_profile_id=[effects_profile_id],
     )
 
-    response = client.synthesize_speech(request={"input": input_text, "voice": voice, "audio_config": audio_config})
+    response = client.synthesize_speech(input=input_text, voice=voice, audio_config=audio_config)
 
     # The response's audio_content is binary.
     with open(output, "wb") as out:

samples/snippets/quickstart.py

@@ -49,7 +49,7 @@ def run_quickstart():
 
     # Perform the text-to-speech request on the text input with the selected
     # voice parameters and audio file type
-    response = client.synthesize_speech(request={"input": synthesis_input, "voice": voice, "audio_config": audio_config})
+    response = client.synthesize_speech(input=input_text, voice=voice, audio_config=audio_config)
 
     # The response's audio_content is binary.
     with open("output.mp3", "wb") as out:

samples/snippets/ssml_addresses.py

@@ -56,7 +56,7 @@ def ssml_to_audio(ssml_text, outfile):
 
     # Performs the text-to-speech request on the text input with the selected
     # voice parameters and audio file type
-    response = client.synthesize_speech(request={"input": synthesis_input, "voice": voice, "audio_config": audio_config})
+    response = client.synthesize_speech(input=synthesis_input, voice=voice, audio_config=audio_config)
 
     # Writes the synthetic audio to the output file.
     with open(outfile, "wb") as out:

samples/snippets/synthesize_file.py

@@ -81,7 +81,7 @@ def synthesize_ssml_file(ssml_file):
         audio_encoding=texttospeech.AudioEncoding.MP3
     )
 
-    response = client.synthesize_speech(request={"input": input_text, "voice": voice, "audio_config": audio_config})
+    response = client.synthesize_speech(input=input_text, voice=voice, audio_config=audio_config)
 
     # The response's audio_content is binary.
     with open("output.mp3", "wb") as out:

samples/snippets/synthesize_text.py

@@ -83,7 +83,7 @@ def synthesize_ssml(ssml):
         audio_encoding=texttospeech.AudioEncoding.MP3
     )
 
-    response = client.synthesize_speech(request={"input": input_text, "voice": voice, "audio_config": audio_config})
+    response = client.synthesize_speech(input=input_text, voice=voice, audio_config=audio_config)
 
     # The response's audio_content is binary.
     with open("output.mp3", "wb") as out: