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 <[email protected]>

* Update summary_overview.md

* Update README.rst

* Update README.rst

* Apply suggestions from code review

Co-authored-by: Anthonios Partheniou <[email protected]>

* docs: exclude docs/summary_overview for non-Cloud libraries

* Update synthtool/gcp/common.py

Co-authored-by: Anthonios Partheniou <[email protected]>

---------

Co-authored-by: Anthonios Partheniou <[email protected]>

Author: dandhlee

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.

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

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)

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

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)