feat(docs): publish Client libraries help to reference documentation

docs/devsite-help/getting-started.md

@@ -0,0 +1,193 @@
+# Getting started with client libraries
+
+The Google Cloud Libraries for Python are a mixture of handwritten and autogenerated
+libraries connecting to Google Cloud services. The handwritten libraries (such
+as [google-cloud-firestore](https://docs.cloud.google.com/python/docs/reference/firestore/latest) and
+[google-cloud-spanner](https://docs.cloud.google.com/python/docs/reference/spanner/latest))
+are mostly higher level abstractions over the underlying API. See the documentation
+for those individual libraries for details; the documentation here is primarily
+aimed at the autogenerated libraries.
+
+If you haven't already found the library for the API you're interested in, please consult
+[the list of Python libraries](https://cloud.google.com/python/docs/reference) which shows both the package
+name and the link to the library-specific documentation. In particular, each library has:
+
+- A "getting started" page which lists the client types within that library
+- Version history for the library
+- API reference documentation
+
+This page demonstrates using the [google-cloud-translate](https://docs.cloud.google.com/python/docs/reference/translate/latest)
+API as a simple example; the steps required for other APIs are very similar.
+
+## Prerequisites
+
+All Google Cloud APIs require a Google Cloud project. If you haven't set one up already,
+please [create one](https://cloud.google.com/resource-manager/docs/creating-managing-projects).
+You'll also need to [enable your chosen API](https://console.cloud.google.com/apis/library) if it hasn't
+already been used within that Google Cloud project.
+
+There are no specific tools required to develop using the Google Cloud Libraries for Python. All
+development environments should work, but you should check that you're targeting a
+[supported version of Python](https://docs.cloud.google.com/python/docs/supported-python-versions).
+
+We recommend installing the [gcloud CLI](https://cloud.google.com/sdk/gcloud).
+
+## Install the library
+
+All Google Cloud Libraries for Python are available from [PyPI](https://pypi.org) and can be installed
+using `pip`. If you wish to install a pre-release version, you can specify the version explicitly
+with the installation command.
+
+The libraries can be installed in any regular environment, including virtual environments (recommended),
+containerized applications, and web frameworks like Django or Flask.
+
+For the translation example, we'll create a new directory, set up a virtual environment,
+and install the package.
+
+Note that for simplicity, the sample code below uses synchronous calls. Most libraries also provide
+asynchronous clients (usually prefixed with `Async`) for use in naturally asynchronous environments
+using `asyncio`.
+
+```sh
+mkdir TranslationExample
+cd TranslationExample
+python3 -m venv venv
+source venv/bin/activate
+pip install google-cloud-translate
+```
+
+> **Dependencies**
+> If you install the library, you may notice
+> a lot of transitive dependencies being installed. This is entirely expected, but you may not recognize
+> some of those dependencies. The list below is not comprehensive, but highlights some of the packages
+> you'll see being installed.
+>
+> - protobuf: the library supporting the [Protocol Buffers](https://protobuf.dev) serialization format
+> - google-api-core: support libraries specifically tailored for the Google Cloud client libraries
+> - google-auth: authentication support for Google Cloud credentials
+> - grpcio: support for the [gRPC](https://grpc.io/) RPC protocol
+> - google-cloud-core: common helpers and support for [long-running operations](https://docs.cloud.google.com/python/docs/reference/google-cloud-core/latest)
+
+## Create a client
+
+The first step in making any API calls is to create a client. Some libraries have multiple clients
+for operations involving different resources; others have a single client. In the Translation API
+we're using, we use `TranslationServiceClient`.
+
+Clients can be configured in a number of ways, but in many cases the defaults are fine. The most
+common reason to use explicit configuration is to use specific credentials for
+[authentication](https://cloud.google.com/docs/authentication/use-cases). For this example, we'll just use
+[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev).
+To set up ADC in your local environment, follow the instructions in
+[Local development environment](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev).
+When you create a client, it automatically detects and uses these credentials.
+
+To create a client with default settings:
+
+```python
+from google.cloud import translate_v3 as translate
+
+client = translate.TranslationServiceClient()
+```
+
+## Make requests
+
+The Google Cloud Libraries use [Protocol Buffers](https://protobuf.dev)
+to represent requests and responses, with some additional types to make the APIs more
+convenient to work with.
+
+Most APIs are expressed in terms of a single request returning a single response, although
+there are also some streaming APIs involving multiple requests and/or multiple responses.
+For our Translation API example, we'll create a simple request for the `translate_text` API.
+
+```python
+from google.cloud import translate_v3 as translate
+
+client = translate.TranslationServiceClient()
+
+project_id = "your-project-id-here"
+location_id = "global"
+parent = f"projects/{project_id}/locations/{location_id}"
+request = translate.TranslateTextRequest(
+    contents=["It is raining.", "It is sunny."],
+    target_language_code="fr-FR",
+    parent=parent
+)
+
+response = client.translate_text(request=request)
+```
+
+This example demonstrates a few features:
+
+- Protocol Buffer messages are instantiated with keyword arguments representing the fields
+- Repeated fields (like `contents`) are represented as Python lists
+- The `parent` field is a string representation of a resource name. The library provides helper methods
+  on the client to construct these paths, ensuring you don't need to concern yourself
+  with the underlying resource name format.
+
+The Google Cloud Libraries always expose methods accepting an API request object directly,
+but they also support passing keyword arguments directly to the method for convenience:
+
+```python
+response = client.translate_text(
+    contents=["It is raining.", "It is sunny."],
+    target_language_code="fr-FR",
+    parent=parent,
+)
+```
+
+The response is also a Protocol Buffers message. You can inspect the structure of the response
+by printing it, or by accessing its attributes directly. In this case we'll look at the
+`translations` attribute:
+
+```python
+print(f"Translations returned: {len(response.translations)}")
+print()
+for translation in response.translations:
+    print(f"Detected language: {translation.detected_language_code}")
+    print(f"Translated text: {translation.translated_text}")
+    print()
+```
+
+This produces output of:
+
+```text
+Translations returned: 2
+
+Detected language: en
+Translated text: Il pleut.
+
+Detected language: en
+Translated text: Il fait beau.
+```
+
+The complete code is:
+
+```python
+from google.cloud import translate_v3 as translate
+
+client = translate.TranslationServiceClient()
+
+project_id = "your-project-id-here"
+location_id = "global"
+parent = f"projects/{project_id}/locations/{location_id}"
+
+request = translate.TranslateTextRequest(
+    contents=["It is raining.", "It is sunny."],
+    target_language_code="fr-FR",
+    parent=parent,
+)
+
+response = client.translate_text(request=request)
+
+print(f"Translations returned: {len(response.translations)}")
+print()
+for translation in response.translations:
+    print(f"Detected language: {translation.detected_language_code}")
+    print(f"Translated text: {translation.translated_text}")
+    print()
+```
+
+This is just a simple example, which hasn't touched on features like pagination
+or specifying call configurations like timeouts and retries.
+

docs/devsite-help/toc.yml

@@ -0,0 +1,6 @@
+- uid: product-neutral-guides
+  name: 'Client library help'
+  items:
+    -
+      name: 'Getting Started'
+      href: 'getting-started.md'

docs/generate-devsite-help.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+
+set -e
+REPOROOT=$(git rev-parse --show-toplevel)
+
+if [[ -z "$1" ]]
+then
+  declare -r VERSION="1.0.0"
+else
+  declare -r VERSION=$1
+fi
+
+DEVSITE_STAGING_BUCKET=docs-staging-v2
+
+rm -rf $REPOROOT/docs/output
+mkdir -p $REPOROOT/docs/output
+
+cp $REPOROOT/docs/devsite-help/* $REPOROOT/docs/output
+cd $REPOROOT/docs/output
+
+# Create the docs metadata.
+docuploader create-metadata \
+  --name help \
+  --version $VERSION \
+  --language python
+
+# Upload the
+docuploader upload . \
+  --staging-bucket="$DEVSITE_STAGING_BUCKET" \
+  --destination-prefix="docfx-" \
+  --metadata-file="docs.metadata"
+
+echo 'Done'