docs: library generation example of Geo (#8745)

Adding an advanced options for client library generation.

generation/new_client/README.md

@@ -57,7 +57,7 @@ You can run these next commands in the home directory (or IdeaProjects). Otherwi
 Confirm pyenv installation succeeded:
 
 ```
-suztomo@suztomo:~$ pyenv
+~$ pyenv
 pyenv 2.3.4
 Usage: pyenv <command> [<args>]
 
@@ -71,7 +71,7 @@ Some useful pyenv commands are:
 ### Install Python 3.9 via pyenv
 
 ```
-suztomo@suztomo:~$ pyenv install 3.9.13
+~$ pyenv install 3.9.13
 Downloading Python-3.9.13.tar.xz...
 -> https://www.python.org/ftp/python/3.9.13/Python-3.9.13.tar.xz
 Installing Python-3.9.13...
@@ -176,6 +176,88 @@ Please create a pull request:
 
 Create a pull request from the change.
 
+## Advanced Options
+
+For the explanation of the available parameters, run:
+`python3.9 generation/new_client/new-client.py generate  --help`.
+
+```
+~/google-cloud-java$ python3.9 generation/new_client/new-client.py generate  --help
+/usr/local/google/home/suztomo/google-cloud-java/generation/new_client
+Usage: new-client.py generate [OPTIONS]
+
+Options:
+  --api_shortname TEXT            Name for the new directory name and
+                                  (default) artifact name  [required]
+  --name-pretty TEXT              The human-friendly name that appears in
+                                  README.md  [required]
+  --product-docs TEXT             Documentation URL that appears in README.md
+                                  [required]
+  --api-description TEXT          Description that appears in README.md
+                                  [required]
+  --release-level [stable|preview]
+                                  A label that appears in repo-metadata.json.
+                                  The first library generation is always
+                                  'preview'.  [default: preview]
+  --transport [grpc|http|both]    A label that appears in repo-metadata.json
+                                  [default: grpc]
+  --language TEXT                 [default: java]
+  --distribution-name TEXT        Maven coordinates of the generated library.
+                                  By default it's com.google.cloud:google-
+                                  cloud-<api_shortname>
+  --api-id TEXT                   The value of the apiid parameter used in
+                                  README.md It has link to https://console.clo
+                                  ud.google.com/flows/enableapi?apiid=<api_id>
+  --requires-billing BOOLEAN      Based on this value, README.md explains
+                                  whether billing setup is needed or not.
+                                  [default: True]
+  --destination-name TEXT         The directory name of the new library. By
+                                  default it's java-<api_shortname>
+  --proto-path TEXT               Path to proto file from the root of the
+                                  googleapis repository to thedirectory that
+                                  contains the proto files (without the
+                                  version).For example, to generate the
+                                  library for 'google/maps/routing/v2', then
+                                  you specify this value as
+                                  'google/maps/routing'  [required]
+  --cloud-api BOOLEAN             If true, the artifact ID of the library is
+                                  'google-cloud-'; otherwise 'google-'
+                                  [default: True]
+  --group-id TEXT                 The group ID of the artifact when
+                                  distribution name is not set  [default:
+                                  com.google.cloud]
+  --owlbot-image TEXT             The owlbot container image used in
+                                  OwlBot.yaml  [default: gcr.io/cloud-devrel-
+                                  public-resources/owlbot-java]
+  --library-type TEXT             A label that appear in repo-metadata.json to
+                                  tell how the library is maintained or
+                                  generated  [default: GAPIC_AUTO]
+  --googleapis-gen-url TEXT       The URL of the repository that has generated
+                                  Java code from proto service definition
+                                  [default:
+                                  https://github.com/googleapis/googleapis-
+                                  gen.git]
+  --help                          Show this message and exit.
+```
+
+Sometimes, a library generation requires special handling for
+Maven coordinates or API ID, especially when the library is not
+specific to Google Cloud. Refer to the following command example when we
+generated Google Maps Routes API Java client library.
+
+```
+~/google-cloud-java$ python3.9 generation/new_client/new-client.py generate \
+  --api_shortname=maps-routing \
+  --proto-path=google/maps/routing \
+  --name-pretty="Routes API" \
+  --product-docs="https://developers.google.com/maps/documentation/routes" \
+  --api-description="Routes API is the next generation, performance optimized version of the existing Directions API and Distance Matrix API. It helps you find the ideal route from A to Z, calculates ETAs and distances for matrices of origin and destination locations, and also offers new features." \
+  --api-id=routes.googleapis.com \
+  --cloud-api=false \
+  --requires-billing=true \
+  --distribution-name="com.google.maps:google-maps-routing"
+```
+
 # Principles
 
 The script should finish creating a pull request even when the newly created
@@ -271,4 +353,4 @@ subprocess.CalledProcessError: Command '['docker', 'run', '--rm', '-v', '/usr/lo
 You have run the `pyenv local 3.9.13` in the `google-cloud-java` repo.
 1. Remove the `.python-version` file in `google-cloud-java`.
 2. `cd ..` out to the parent directory and run `pyenv local 3.9.13` there
-3. `cd google-cloud-java` back into the repo and run the generation script again
+3. `cd google-cloud-java` back into the repo and run the generation script again

generation/new_client/new-client.py

@@ -30,45 +30,126 @@ def main(ctx):
     pass
 
 @main.command()
-@click.option("--api_shortname", required=True, type=str, prompt="Service name? (e.g. automl)")
+@click.option(
+    "--api_shortname",
+    required=True,
+    type=str,
+    prompt="Service name? (e.g. automl)",
+    help="Name for the new directory name and (default) artifact name"
+)
 @click.option(
     "--name-pretty",
     required=True,
     type=str,
     prompt="Pretty name? (e.g. 'Cloud AutoML')",
+    help="The human-friendly name that appears in README.md"
 )
 @click.option(
-    "--product-docs", required=True, type=str, prompt="Product Documentation URL"
+    "--product-docs",
+    required=True,
+    type=str,
+    prompt="Product Documentation URL",
+    help="Documentation URL that appears in README.md"
 )
 @click.option(
     "--api-description",
     required=True,
     type=str,
-    prompt="Description for README. The first sentence is prefixed by the pretty name",
+    prompt="Description for README. The first sentence is prefixed by the "
+           "pretty name",
+    help="Description that appears in README.md"
 )
 @click.option(
     "--release-level",
     type=click.Choice(["stable", "preview"]),
     default="preview",
+    show_default=True,
+    help="A label that appears in repo-metadata.json. The first library "
+         "generation is always 'preview'."
 )
 @click.option(
     "--transport",
     type=click.Choice(["grpc", "http", "both"]),
     default="grpc",
+    show_default=True,
+    help="A label that appears in repo-metadata.json"
+)
+@click.option("--language", type=str, default="java", show_default=True)
+@click.option(
+    "--distribution-name",
+    type=str,
+    help="Maven coordinates of the generated library. By default it's "
+         "com.google.cloud:google-cloud-<api_shortname>"
+)
+@click.option(
+    "--api-id",
+    type=str,
+    help="The value of the apiid parameter used in README.md It has link to "
+         "https://console.cloud.google.com/flows/enableapi?apiid=<api_id>"
+)
+@click.option(
+    "--requires-billing",
+    type=bool,
+    default=True,
+    show_default=True,
+    help="Based on this value, README.md explains whether billing setup is "
+         "needed or not."
+)
+@click.option(
+    "--destination-name",
+    type=str,
+    default=None,
+    help="The directory name of the new library. By default it's "
+         "java-<api_shortname>"
 )
-@click.option("--language", type=str, default="java")
-@click.option("--distribution-name", type=str)
-@click.option("--api-id", type=str)
-@click.option("--requires-billing", type=bool, default=True)
-@click.option("--destination-name", type=str, default=None)
-@click.option("--proto-path", required=True, type=str, default=None)
-@click.option("--cloud-api", type=bool, default=True)
-@click.option("--group-id", type=str, default="com.google.cloud")
 @click.option(
-    "--owlbot-image", type=str, default="gcr.io/cloud-devrel-public-resources/owlbot-java"
+    "--proto-path",
+    required=True,
+    type=str,
+    default=None,
+    help="Path to proto file from the root of the googleapis repository to the"
+         "directory that contains the proto files (without the version)."
+         "For example, to generate the library for 'google/maps/routing/v2', "
+         "then you specify this value as 'google/maps/routing'"
+)
+@click.option(
+    "--cloud-api",
+    type=bool,
+    default=True,
+    show_default=True,
+    help="If true, the artifact ID of the library is 'google-cloud-'; "
+         "otherwise 'google-'"
+)
+@click.option(
+    "--group-id",
+    type=str,
+    default="com.google.cloud",
+    show_default=True,
+    help="The group ID of the artifact when distribution name is not set"
+)
+@click.option(
+    "--owlbot-image",
+    type=str,
+    default="gcr.io/cloud-devrel-public-resources/owlbot-java",
+    show_default=True,
+    help="The owlbot container image used in OwlBot.yaml"
+)
+@click.option(
+    "--library-type",
+    type=str,
+    default="GAPIC_AUTO",
+    show_default=True,
+    help="A label that appear in repo-metadata.json to tell how the library is "
+         "maintained or generated"
+)
+@click.option(
+    "--googleapis-gen-url",
+    type=str,
+    default="https://github.com/googleapis/googleapis-gen.git",
+    show_default=True,
+    help="The URL of the repository that has generated Java code from proto "
+         "service definition"
 )
-@click.option("--library-type", type=str)
-@click.option("--googleapis-gen-url", type=str, default="https://github.com/googleapis/googleapis-gen.git")
 def generate(
     api_shortname,
     name_pretty,
@@ -99,9 +180,6 @@ def generate(
     if api_id is None:
         api_id = f"{api_shortname}.googleapis.com"
 
-    if library_type is None:
-        library_type = "GAPIC_AUTO"
-
     if not product_docs.startswith("https"):
         sys.exit("product_docs must starts with 'https://'")