From 53468dcb70a90e7478f9b581d9e5599c981f9016 Mon Sep 17 00:00:00 2001 From: Dan Lee Date: Mon, 1 Apr 2024 09:14:15 +0000 Subject: [PATCH 01/10] docs: add summary_overview template --- .../docs/summary_overview.md.j2 | 22 +++++++++++++++++++ .../docs/summary_overview.md.j2 | 22 +++++++++++++++++++ 2 files changed, 44 insertions(+) create mode 100644 synthtool/gcp/templates/python_library/docs/summary_overview.md.j2 create mode 100644 synthtool/gcp/templates/python_mono_repo_library/docs/summary_overview.md.j2 diff --git a/synthtool/gcp/templates/python_library/docs/summary_overview.md.j2 b/synthtool/gcp/templates/python_library/docs/summary_overview.md.j2 new file mode 100644 index 000000000..345bfcff9 --- /dev/null +++ b/synthtool/gcp/templates/python_library/docs/summary_overview.md.j2 @@ -0,0 +1,22 @@ +[ +This is a templated file. Adding content to this file may result in it being +reverted. Instead, if you want to place additional content, use +"overview_content.md" file in `docs/` directory. The Sphinx tool will +pick up on the content and merge the content. +]: # + +# {{ metadata['repo']['name'] }} API + +Overview of the APIs available for {{ metadata['repo']['name'] }} API. + +## All entries + +Take a look at all classes, methods and properties & attributes for +{{ metadata['repo']['name'] }} API. + +[classes]({{ metadata['repo']['client_documentation'] }}/summary_class.html) + +[methods]({{ metadata['repo']['client_documentation'] }}/summary_method.html) + +[properties and +attributes]({{ metadata['repo']['client_documentation'] }}/summary_property.html) diff --git a/synthtool/gcp/templates/python_mono_repo_library/docs/summary_overview.md.j2 b/synthtool/gcp/templates/python_mono_repo_library/docs/summary_overview.md.j2 new file mode 100644 index 000000000..345bfcff9 --- /dev/null +++ b/synthtool/gcp/templates/python_mono_repo_library/docs/summary_overview.md.j2 @@ -0,0 +1,22 @@ +[ +This is a templated file. Adding content to this file may result in it being +reverted. Instead, if you want to place additional content, use +"overview_content.md" file in `docs/` directory. The Sphinx tool will +pick up on the content and merge the content. +]: # + +# {{ metadata['repo']['name'] }} API + +Overview of the APIs available for {{ metadata['repo']['name'] }} API. + +## All entries + +Take a look at all classes, methods and properties & attributes for +{{ metadata['repo']['name'] }} API. + +[classes]({{ metadata['repo']['client_documentation'] }}/summary_class.html) + +[methods]({{ metadata['repo']['client_documentation'] }}/summary_method.html) + +[properties and +attributes]({{ metadata['repo']['client_documentation'] }}/summary_property.html) From 87ec49d7653a9ad16249f238391413f12f9aaaf9 Mon Sep 17 00:00:00 2001 From: Dan Lee Date: Mon, 1 Apr 2024 09:18:40 +0000 Subject: [PATCH 02/10] docs: update README link to summary overview --- synthtool/gcp/templates/python_library/README.rst | 2 +- synthtool/gcp/templates/python_mono_repo_library/README.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/synthtool/gcp/templates/python_library/README.rst b/synthtool/gcp/templates/python_library/README.rst index 5ec6a01da..5aa621f55 100644 --- a/synthtool/gcp/templates/python_library/README.rst +++ b/synthtool/gcp/templates/python_library/README.rst @@ -15,7 +15,7 @@ Python Client for {{ metadata['repo']['name_pretty'] }} API .. |versions| image:: https://img.shields.io/pypi/pyversions/{{ metadata['repo']['distribution_name'] }}.svg :target: https://pypi.org/project/{{ metadata['repo']['distribution_name'] }}/ .. _{{ metadata['repo']['name_pretty'] }} API: {{ metadata['repo']['product_documentation'] }} -.. _Client Library Documentation: {{ metadata['repo']['client_documentation'] }} +.. _Client Library Documentation: {{ metadata['repo']['client_documentation']/summary_overview }} .. _Product Documentation: {{ metadata['repo']['product_documentation'] }} Quick Start diff --git a/synthtool/gcp/templates/python_mono_repo_library/README.rst b/synthtool/gcp/templates/python_mono_repo_library/README.rst index 4a49fe696..e23918210 100644 --- a/synthtool/gcp/templates/python_mono_repo_library/README.rst +++ b/synthtool/gcp/templates/python_mono_repo_library/README.rst @@ -15,7 +15,7 @@ Python Client for {{ metadata['repo']['name_pretty'] }} .. |versions| image:: https://img.shields.io/pypi/pyversions/{{ metadata['repo']['distribution_name'] }}.svg :target: https://pypi.org/project/{{ metadata['repo']['distribution_name'] }}/ .. _{{ metadata['repo']['name_pretty'] }}: {{ metadata['repo']['product_documentation'] }} -.. _Client Library Documentation: {{ metadata['repo']['client_documentation'] }} +.. _Client Library Documentation: {{ metadata['repo']['client_documentation']/summary_overview }} .. _Product Documentation: {{ metadata['repo']['product_documentation'] }} Quick Start From f3be8ba207fd2b9239e2808ae04477bfbb1ff501 Mon Sep 17 00:00:00 2001 From: Dan Lee Date: Mon, 1 Apr 2024 10:09:04 +0000 Subject: [PATCH 03/10] docs: fix readme link --- synthtool/gcp/templates/python_library/README.rst | 2 +- .../docs/{summary_overview.md.j2 => summary_overview.md} | 0 synthtool/gcp/templates/python_mono_repo_library/README.rst | 2 +- .../docs/{summary_overview.md.j2 => summary_overview.md} | 0 4 files changed, 2 insertions(+), 2 deletions(-) rename synthtool/gcp/templates/python_library/docs/{summary_overview.md.j2 => summary_overview.md} (100%) rename synthtool/gcp/templates/python_mono_repo_library/docs/{summary_overview.md.j2 => summary_overview.md} (100%) diff --git a/synthtool/gcp/templates/python_library/README.rst b/synthtool/gcp/templates/python_library/README.rst index 5aa621f55..9fc92c969 100644 --- a/synthtool/gcp/templates/python_library/README.rst +++ b/synthtool/gcp/templates/python_library/README.rst @@ -15,7 +15,7 @@ Python Client for {{ metadata['repo']['name_pretty'] }} API .. |versions| image:: https://img.shields.io/pypi/pyversions/{{ metadata['repo']['distribution_name'] }}.svg :target: https://pypi.org/project/{{ metadata['repo']['distribution_name'] }}/ .. _{{ metadata['repo']['name_pretty'] }} API: {{ metadata['repo']['product_documentation'] }} -.. _Client Library Documentation: {{ metadata['repo']['client_documentation']/summary_overview }} +.. _Client Library Documentation: {{ metadata['repo']['client_documentation'] }}/summary_overview .. _Product Documentation: {{ metadata['repo']['product_documentation'] }} Quick Start diff --git a/synthtool/gcp/templates/python_library/docs/summary_overview.md.j2 b/synthtool/gcp/templates/python_library/docs/summary_overview.md similarity index 100% rename from synthtool/gcp/templates/python_library/docs/summary_overview.md.j2 rename to synthtool/gcp/templates/python_library/docs/summary_overview.md diff --git a/synthtool/gcp/templates/python_mono_repo_library/README.rst b/synthtool/gcp/templates/python_mono_repo_library/README.rst index e23918210..46478bf8d 100644 --- a/synthtool/gcp/templates/python_mono_repo_library/README.rst +++ b/synthtool/gcp/templates/python_mono_repo_library/README.rst @@ -15,7 +15,7 @@ Python Client for {{ metadata['repo']['name_pretty'] }} .. |versions| image:: https://img.shields.io/pypi/pyversions/{{ metadata['repo']['distribution_name'] }}.svg :target: https://pypi.org/project/{{ metadata['repo']['distribution_name'] }}/ .. _{{ metadata['repo']['name_pretty'] }}: {{ metadata['repo']['product_documentation'] }} -.. _Client Library Documentation: {{ metadata['repo']['client_documentation']/summary_overview }} +.. _Client Library Documentation: {{ metadata['repo']['client_documentation'] }}/summary_overview .. _Product Documentation: {{ metadata['repo']['product_documentation'] }} Quick Start diff --git a/synthtool/gcp/templates/python_mono_repo_library/docs/summary_overview.md.j2 b/synthtool/gcp/templates/python_mono_repo_library/docs/summary_overview.md similarity index 100% rename from synthtool/gcp/templates/python_mono_repo_library/docs/summary_overview.md.j2 rename to synthtool/gcp/templates/python_mono_repo_library/docs/summary_overview.md From 7b8e2aabbe73ff5bd5dba5a550914692c01eee9a Mon Sep 17 00:00:00 2001 From: Dan Lee <71398022+dandhlee@users.noreply.github.com> Date: Wed, 3 Apr 2024 13:55:05 -0400 Subject: [PATCH 04/10] Apply suggestions from code review Co-authored-by: Anthonios Partheniou --- .../gcp/templates/python_library/docs/summary_overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/synthtool/gcp/templates/python_library/docs/summary_overview.md b/synthtool/gcp/templates/python_library/docs/summary_overview.md index 345bfcff9..b165a21c3 100644 --- a/synthtool/gcp/templates/python_library/docs/summary_overview.md +++ b/synthtool/gcp/templates/python_library/docs/summary_overview.md @@ -11,8 +11,8 @@ Overview of the APIs available for {{ metadata['repo']['name'] }} API. ## All entries -Take a look at all classes, methods and properties & attributes for -{{ metadata['repo']['name'] }} API. +Classes, methods and properties & attributes for +{{ metadata['repo']['name_pretty'] }} API. [classes]({{ metadata['repo']['client_documentation'] }}/summary_class.html) From 83500a7732a276c94de6e12eb00d49cd4af80ae0 Mon Sep 17 00:00:00 2001 From: Dan Lee <71398022+dandhlee@users.noreply.github.com> Date: Wed, 3 Apr 2024 13:55:59 -0400 Subject: [PATCH 05/10] Update summary_overview.md --- .../python_mono_repo_library/docs/summary_overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/synthtool/gcp/templates/python_mono_repo_library/docs/summary_overview.md b/synthtool/gcp/templates/python_mono_repo_library/docs/summary_overview.md index 345bfcff9..b165a21c3 100644 --- a/synthtool/gcp/templates/python_mono_repo_library/docs/summary_overview.md +++ b/synthtool/gcp/templates/python_mono_repo_library/docs/summary_overview.md @@ -11,8 +11,8 @@ Overview of the APIs available for {{ metadata['repo']['name'] }} API. ## All entries -Take a look at all classes, methods and properties & attributes for -{{ metadata['repo']['name'] }} API. +Classes, methods and properties & attributes for +{{ metadata['repo']['name_pretty'] }} API. [classes]({{ metadata['repo']['client_documentation'] }}/summary_class.html) From ec6ddef6ad5d9dcae58ece4db18e01ae4d11764c Mon Sep 17 00:00:00 2001 From: Dan Lee <71398022+dandhlee@users.noreply.github.com> Date: Fri, 5 Apr 2024 07:57:57 -0400 Subject: [PATCH 06/10] Update README.rst --- synthtool/gcp/templates/python_library/README.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/synthtool/gcp/templates/python_library/README.rst b/synthtool/gcp/templates/python_library/README.rst index 9fc92c969..b1e3fd7ec 100644 --- a/synthtool/gcp/templates/python_library/README.rst +++ b/synthtool/gcp/templates/python_library/README.rst @@ -15,7 +15,11 @@ Python Client for {{ metadata['repo']['name_pretty'] }} API .. |versions| image:: https://img.shields.io/pypi/pyversions/{{ metadata['repo']['distribution_name'] }}.svg :target: https://pypi.org/project/{{ metadata['repo']['distribution_name'] }}/ .. _{{ metadata['repo']['name_pretty'] }} API: {{ metadata['repo']['product_documentation'] }} +{%- if is_google_cloud_api %} .. _Client Library Documentation: {{ metadata['repo']['client_documentation'] }}/summary_overview +{% else %} +.. _Client Library Documentation: {{ metadata['repo']['client_documentation'] }} +{% endif -%} .. _Product Documentation: {{ metadata['repo']['product_documentation'] }} Quick Start From 5fea434cbc04162f0d6f51b55fa15e29ad8bad37 Mon Sep 17 00:00:00 2001 From: Dan Lee <71398022+dandhlee@users.noreply.github.com> Date: Fri, 5 Apr 2024 07:59:06 -0400 Subject: [PATCH 07/10] Update README.rst --- synthtool/gcp/templates/python_mono_repo_library/README.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/synthtool/gcp/templates/python_mono_repo_library/README.rst b/synthtool/gcp/templates/python_mono_repo_library/README.rst index 46478bf8d..930d543f0 100644 --- a/synthtool/gcp/templates/python_mono_repo_library/README.rst +++ b/synthtool/gcp/templates/python_mono_repo_library/README.rst @@ -15,7 +15,11 @@ Python Client for {{ metadata['repo']['name_pretty'] }} .. |versions| image:: https://img.shields.io/pypi/pyversions/{{ metadata['repo']['distribution_name'] }}.svg :target: https://pypi.org/project/{{ metadata['repo']['distribution_name'] }}/ .. _{{ metadata['repo']['name_pretty'] }}: {{ metadata['repo']['product_documentation'] }} +{%- if is_google_cloud_api %} .. _Client Library Documentation: {{ metadata['repo']['client_documentation'] }}/summary_overview +{% else %} +.. _Client Library Documentation: {{ metadata['repo']['client_documentation'] }} +{% endif -%} .. _Product Documentation: {{ metadata['repo']['product_documentation'] }} Quick Start From 48bcff6a0e380b4012ec7981f48cc5565e5c09fa Mon Sep 17 00:00:00 2001 From: Dan Lee <71398022+dandhlee@users.noreply.github.com> Date: Fri, 5 Apr 2024 07:59:46 -0400 Subject: [PATCH 08/10] Apply suggestions from code review Co-authored-by: Anthonios Partheniou --- .../gcp/templates/python_library/docs/summary_overview.md | 6 +++--- .../python_mono_repo_library/docs/summary_overview.md | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/synthtool/gcp/templates/python_library/docs/summary_overview.md b/synthtool/gcp/templates/python_library/docs/summary_overview.md index b165a21c3..2b8beb5be 100644 --- a/synthtool/gcp/templates/python_library/docs/summary_overview.md +++ b/synthtool/gcp/templates/python_library/docs/summary_overview.md @@ -1,13 +1,13 @@ [ This is a templated file. Adding content to this file may result in it being -reverted. Instead, if you want to place additional content, use +reverted. Instead, if you want to place additional content, create an "overview_content.md" file in `docs/` directory. The Sphinx tool will pick up on the content and merge the content. ]: # -# {{ metadata['repo']['name'] }} API +# {{ metadata['repo']['name_pretty'] }} API -Overview of the APIs available for {{ metadata['repo']['name'] }} API. +Overview of the APIs available for {{ metadata['repo']['name_pretty'] }} API. ## All entries diff --git a/synthtool/gcp/templates/python_mono_repo_library/docs/summary_overview.md b/synthtool/gcp/templates/python_mono_repo_library/docs/summary_overview.md index b165a21c3..2b8beb5be 100644 --- a/synthtool/gcp/templates/python_mono_repo_library/docs/summary_overview.md +++ b/synthtool/gcp/templates/python_mono_repo_library/docs/summary_overview.md @@ -1,13 +1,13 @@ [ This is a templated file. Adding content to this file may result in it being -reverted. Instead, if you want to place additional content, use +reverted. Instead, if you want to place additional content, create an "overview_content.md" file in `docs/` directory. The Sphinx tool will pick up on the content and merge the content. ]: # -# {{ metadata['repo']['name'] }} API +# {{ metadata['repo']['name_pretty'] }} API -Overview of the APIs available for {{ metadata['repo']['name'] }} API. +Overview of the APIs available for {{ metadata['repo']['name_pretty'] }} API. ## All entries From 2b040ef850ee26279385f5c03bbdf1d8557cf209 Mon Sep 17 00:00:00 2001 From: Dan Lee Date: Fri, 5 Apr 2024 18:03:31 +0000 Subject: [PATCH 09/10] docs: exclude docs/summary_overview for non-Cloud libraries --- synthtool/gcp/common.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/synthtool/gcp/common.py b/synthtool/gcp/common.py index f33e7136b..f3ad52041 100644 --- a/synthtool/gcp/common.py +++ b/synthtool/gcp/common.py @@ -235,6 +235,8 @@ def py_mono_repo_library(self, relative_dir, **kwargs) -> Path: # If the directory `google/cloud` exists, add kwargs to signal that the client library is for a Cloud API if Path("google/cloud").exists(): kwargs["is_google_cloud_api"] = True + else: + self.excludes += ["docs/summary_overview.md"] return self._generic_library("python_mono_repo_library", relative_dir, **kwargs) @@ -299,6 +301,8 @@ def py_library(self, **kwargs) -> Path: # If the directory `google/cloud` exists, add kwargs to signal that the client library is for a Cloud API if Path("google/cloud").exists(): kwargs["is_google_cloud_api"] = True + else: + self.excludes += ["docs/summary_overview.md"] # If Dockerfile exists in .kokoro/docker/samples, add kwargs to # signal that a custom docker image should be used when testing samples. From 9472112bcd0fcd36ff77c48fe9bb831a82d57579 Mon Sep 17 00:00:00 2001 From: Dan Lee <71398022+dandhlee@users.noreply.github.com> Date: Fri, 5 Apr 2024 14:38:37 -0400 Subject: [PATCH 10/10] Update synthtool/gcp/common.py Co-authored-by: Anthonios Partheniou --- synthtool/gcp/common.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/synthtool/gcp/common.py b/synthtool/gcp/common.py index f3ad52041..c4519aa2f 100644 --- a/synthtool/gcp/common.py +++ b/synthtool/gcp/common.py @@ -233,7 +233,7 @@ def py_mono_repo_library(self, relative_dir, **kwargs) -> Path: self.excludes += ["docs/index.rst"] # If the directory `google/cloud` exists, add kwargs to signal that the client library is for a Cloud API - if Path("google/cloud").exists(): + if Path(f"{relative_dir}/google/cloud").exists(): kwargs["is_google_cloud_api"] = True else: self.excludes += ["docs/summary_overview.md"]