From 4599843019d2eeb1f6c0d5f23556b7b014eca1b3 Mon Sep 17 00:00:00 2001 From: Tomo Suzuki Date: Tue, 8 Nov 2022 15:54:15 -0500 Subject: [PATCH 1/4] docs: library generation example of Geo --- generation/new_client/README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/generation/new_client/README.md b/generation/new_client/README.md index 0babb2722c0e..8e47c769c926 100644 --- a/generation/new_client/README.md +++ b/generation/new_client/README.md @@ -161,6 +161,26 @@ Please create a pull request: Create a pull request from the change. +## Advanced Options + +Sometimes, a library generation requires special handling for +Maven coordinates or API ID, especially when the library is not +specific to Google Cloud. Use the following example of Google +Maps API to generate a module for such 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 From bdf2f3fac07d56488997ef00e9ba9c2109410e9f Mon Sep 17 00:00:00 2001 From: Tomo Suzuki Date: Wed, 9 Nov 2022 10:37:09 -0500 Subject: [PATCH 2/4] Added help options. --- generation/new_client/README.md | 58 +++++++++++++++- generation/new_client/new-client.py | 102 +++++++++++++++++++++++----- 2 files changed, 142 insertions(+), 18 deletions(-) diff --git a/generation/new_client/README.md b/generation/new_client/README.md index 8e47c769c926..4c98a22f6abd 100644 --- a/generation/new_client/README.md +++ b/generation/new_client/README.md @@ -163,10 +163,64 @@ 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`. + +``` +suztomo@suztomo2:~/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'. + --transport [grpc|http|both] A label that appears in repo-metadata.json + --language TEXT + --distribution-name TEXT Maven coordinates of the generated library. + By default it's com.google.cloud:google- + cloud- + --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= + --requires-billing BOOLEAN Based on this value, README.md explains + whether billing setup is needed or not. + --destination-name TEXT The directory name of the new library. By + default it's java- + --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-' + --group-id TEXT The group ID of the artifact when + distribution name is not set + --owlbot-image TEXT The owlbot container image used in + OwlBot.yaml + --library-type TEXT A label that appear in repo-metadata.json to + tell how the library is maintained or + generated + --googleapis-gen-url TEXT The URL of the repository that has generated + Java code from proto service definition + --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. Use the following example of Google -Maps API to generate a module for such library: +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 \ diff --git a/generation/new_client/new-client.py b/generation/new_client/new-client.py index 047e6e6b0891..e968e9a6b84f 100644 --- a/generation/new_client/new-client.py +++ b/generation/new_client/new-client.py @@ -30,45 +30,118 @@ 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", + 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", + help="A label that appears in repo-metadata.json" ) @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" + "--distribution-name", + type=str, + help="Maven coordinates of the generated library. By default it's " + "com.google.cloud:google-cloud-" +) +@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=" +) +@click.option( + "--requires-billing", + type=bool, + 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-" +) +@click.option( + "--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, + help="If true, the artifact ID of the library is 'google-cloud-'; " + "otherwise 'google-'" +) +@click.option( + "--group-id", + type=str, + default="com.google.cloud", + 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", + help="The owlbot container image used in OwlBot.yaml" +) +@click.option( + "--library-type", + type=str, + default="GAPIC_AUTO", + 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", + 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 +172,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://'") From 2ceb9e3b7b332b4dcea4d4c8b247026b2998ff0e Mon Sep 17 00:00:00 2001 From: Tomo Suzuki Date: Wed, 9 Nov 2022 10:40:15 -0500 Subject: [PATCH 3/4] removing unnecessary account name in prompt --- generation/new_client/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/generation/new_client/README.md b/generation/new_client/README.md index 4c98a22f6abd..daef3a589e0b 100644 --- a/generation/new_client/README.md +++ b/generation/new_client/README.md @@ -48,7 +48,7 @@ Logout the shell and login again. Confirm pyenv installation succeeded: ``` -suztomo@suztomo:~$ pyenv +~$ pyenv pyenv 2.3.4 Usage: pyenv [] @@ -62,7 +62,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... @@ -167,7 +167,7 @@ For the explanation of the available parameters, run: `python3.9 generation/new_client/new-client.py generate --help`. ``` -suztomo@suztomo2:~/google-cloud-java$ 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] From 37be2cf49754ed3555ce39297ccf606fb25fb6cf Mon Sep 17 00:00:00 2001 From: Tomo Suzuki Date: Mon, 5 Dec 2022 20:19:34 +0000 Subject: [PATCH 4/4] show default value in help As per https://click.palletsprojects.com/en/8.1.x/options/ we can show the default value in help if we specify show_default= True --- generation/new_client/README.md | 20 ++++++++++++++------ generation/new_client/new-client.py | 10 +++++++++- 2 files changed, 23 insertions(+), 7 deletions(-) diff --git a/generation/new_client/README.md b/generation/new_client/README.md index 2b99ae8e6e79..5a6a80e70301 100644 --- a/generation/new_client/README.md +++ b/generation/new_client/README.md @@ -198,9 +198,10 @@ Options: --release-level [stable|preview] A label that appears in repo-metadata.json. The first library generation is always - 'preview'. + 'preview'. [default: preview] --transport [grpc|http|both] A label that appears in repo-metadata.json - --language TEXT + [default: grpc] + --language TEXT [default: java] --distribution-name TEXT Maven coordinates of the generated library. By default it's com.google.cloud:google- cloud- @@ -209,6 +210,7 @@ Options: ud.google.com/flows/enableapi?apiid= --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- --proto-path TEXT Path to proto file from the root of the @@ -220,15 +222,21 @@ Options: '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 + distribution name is not set [default: + com.google.cloud] --owlbot-image TEXT The owlbot container image used in - OwlBot.yaml + 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 + 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. ``` @@ -345,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 \ No newline at end of file +3. `cd google-cloud-java` back into the repo and run the generation script again diff --git a/generation/new_client/new-client.py b/generation/new_client/new-client.py index aad5a747452d..4fd7cc0abcd4 100644 --- a/generation/new_client/new-client.py +++ b/generation/new_client/new-client.py @@ -63,6 +63,7 @@ def main(ctx): "--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'." ) @@ -70,9 +71,10 @@ def main(ctx): "--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") +@click.option("--language", type=str, default="java", show_default=True) @click.option( "--distribution-name", type=str, @@ -89,6 +91,7 @@ def main(ctx): "--requires-billing", type=bool, default=True, + show_default=True, help="Based on this value, README.md explains whether billing setup is " "needed or not." ) @@ -113,6 +116,7 @@ def main(ctx): "--cloud-api", type=bool, default=True, + show_default=True, help="If true, the artifact ID of the library is 'google-cloud-'; " "otherwise 'google-'" ) @@ -120,18 +124,21 @@ def main(ctx): "--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" ) @@ -139,6 +146,7 @@ def main(ctx): "--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" )