From d7c2271d319aeb7e3043ec3f1ecec6f3604f1f1e Mon Sep 17 00:00:00 2001 From: Dan Lee <71398022+dandhlee@users.noreply.github.com> Date: Fri, 5 Apr 2024 15:45:46 -0400 Subject: [PATCH] docs: add summary_overview template (#1946) * docs: add summary_overview template * docs: update README link to summary overview * docs: fix readme link * Apply suggestions from code review Co-authored-by: Anthonios Partheniou * Update summary_overview.md * Update README.rst * Update README.rst * Apply suggestions from code review Co-authored-by: Anthonios Partheniou * docs: exclude docs/summary_overview for non-Cloud libraries * Update synthtool/gcp/common.py Co-authored-by: Anthonios Partheniou --------- Co-authored-by: Anthonios Partheniou --- synthtool/gcp/common.py | 6 ++++- .../gcp/templates/python_library/README.rst | 4 ++++ .../python_library/docs/summary_overview.md | 22 +++++++++++++++++++ .../python_mono_repo_library/README.rst | 4 ++++ .../docs/summary_overview.md | 22 +++++++++++++++++++ 5 files changed, 57 insertions(+), 1 deletion(-) create mode 100644 synthtool/gcp/templates/python_library/docs/summary_overview.md create mode 100644 synthtool/gcp/templates/python_mono_repo_library/docs/summary_overview.md diff --git a/synthtool/gcp/common.py b/synthtool/gcp/common.py index f33e7136b..c4519aa2f 100644 --- a/synthtool/gcp/common.py +++ b/synthtool/gcp/common.py @@ -233,8 +233,10 @@ 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"] 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. diff --git a/synthtool/gcp/templates/python_library/README.rst b/synthtool/gcp/templates/python_library/README.rst index 5ec6a01da..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 diff --git a/synthtool/gcp/templates/python_library/docs/summary_overview.md b/synthtool/gcp/templates/python_library/docs/summary_overview.md new file mode 100644 index 000000000..2b8beb5be --- /dev/null +++ b/synthtool/gcp/templates/python_library/docs/summary_overview.md @@ -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, 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_pretty'] }} API + +Overview of the APIs available for {{ metadata['repo']['name_pretty'] }} API. + +## All entries + +Classes, methods and properties & attributes for +{{ metadata['repo']['name_pretty'] }} 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/README.rst b/synthtool/gcp/templates/python_mono_repo_library/README.rst index 4a49fe696..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 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 new file mode 100644 index 000000000..2b8beb5be --- /dev/null +++ b/synthtool/gcp/templates/python_mono_repo_library/docs/summary_overview.md @@ -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, 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_pretty'] }} API + +Overview of the APIs available for {{ metadata['repo']['name_pretty'] }} API. + +## All entries + +Classes, methods and properties & attributes for +{{ metadata['repo']['name_pretty'] }} 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)