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 <partheniou@google.com> * Update summary_overview.md * Update README.rst * Update README.rst * Apply suggestions from code review Co-authored-by: Anthonios Partheniou <partheniou@google.com> * docs: exclude docs/summary_overview for non-Cloud libraries * Update synthtool/gcp/common.py Co-authored-by: Anthonios Partheniou <partheniou@google.com> --------- Co-authored-by: Anthonios Partheniou <partheniou@google.com>
googleapis · Apr 5, 2024 · d7c2271 · d7c2271
1 parent 4b49307
commit d7c2271
Show file tree

Hide file tree

Showing 5 changed files with 57 additions and 1 deletion.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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)