docs: sync README with synthtool templates

Author: parthea

gapic/schema/naming.py

@@ -45,6 +45,11 @@ class Naming(abc.ABC):
     proto_package: str = ""
     _warehouse_package_name: str = ""
     proto_plus_deps: Tuple[str, ...] = dataclasses.field(default_factory=tuple)
+    api_description: str = ""
+    _documentation_name: str = ""
+    documentation_uri: str = ""
+    release_level: str = ""
+    title: str = ""
 
     def __post_init__(self):
         if not self.product_name:
@@ -154,6 +159,30 @@ def build(
             package_info = dataclasses.replace(
                 package_info, _warehouse_package_name=opts.warehouse_package_name
             )
+
+        if opts.api_description:
+            package_info = dataclasses.replace(
+                package_info, api_description=opts.api_description
+            )
+
+        if opts.documentation_name:
+            package_info = dataclasses.replace(
+                package_info, _documentation_name=opts.documentation_name
+            )
+
+        if opts.documentation_uri:
+            package_info = dataclasses.replace(
+                package_info, documentation_uri=opts.documentation_uri
+            )
+
+        if opts.release_level:
+            package_info = dataclasses.replace(
+                package_info, release_level=opts.release_level
+            )
+
+        if opts.title:
+            package_info = dataclasses.replace(package_info, title=opts.title)
+
         if opts.proto_plus_deps:
             package_info = dataclasses.replace(
                 package_info,
@@ -212,6 +241,15 @@ def warehouse_package_name(self) -> str:
         answer = list(self.namespace) + self.name.split(" ")
         return "-".join(answer).lower()
 
+    @property
+    def documentation_name(self) -> str:
+        """Return the appropriate name for documentation."""
+        # If a custom name has been set, use it
+        if self._documentation_name:
+            return self._documentation_name
+        # Otherwise use `name` for backwards compatibility
+        return self.name.lower()
+
 
 class NewNaming(Naming):
     @property

gapic/templates/README.rst.j2

@@ -1,5 +1,28 @@
-Python Client for {{ api.naming.long_name }} API
-=================================================
+Python Client for {{ api.naming.title }}
+=================={% for i in range( api.naming.title | length ) %}={% endfor %}
+
+
+|{{ api.naming.release_level }}| |pypi| |versions|
+
+`{{ api.naming.title }}`_: {% if api.naming.api_description %}{{ api.naming.api_description.replace("\n", " ") }}{% endif %}
+
+
+- `Client Library Documentation`_
+- `Product Documentation`_
+
+.. |{{ api.naming.release_level }}| image:: https://img.shields.io/badge/support-{{ api.naming.release_level }}-{% if api.naming.release_level == "stable" %}gold{% else %}orange{% endif %}.svg
+   :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels
+.. |pypi| image:: https://img.shields.io/pypi/v/{{ api.naming.warehouse_package_name }}.svg
+   :target: https://pypi.org/project/{{ api.naming.warehouse_package_name }}/
+.. |versions| image:: https://img.shields.io/pypi/pyversions/{{ api.naming.warehouse_package_name }}.svg
+   :target: https://pypi.org/project/{{ api.naming.warehouse_package_name }}/
+.. _{{ api.naming.title }}: {{ api.naming.documentation_uri }}
+{% if api.naming.module_namespace|length >= 2 and api.naming.module_namespace[0] == "google" and api.naming.module_namespace[1] == "cloud" %}
+.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/{{ api.naming.documentation_name }}/latest/summary_overview
+{% else %}
+.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/{{ api.naming.documentation_name }}/latest
+{% endif %}
+.. _Product Documentation:  {{ api.naming.documentation_uri }}
 
 Quick Start
 -----------
@@ -8,26 +31,55 @@ In order to use this library, you first need to go through the following steps:
 
 1. `Select or create a Cloud Platform project.`_
 2. `Enable billing for your project.`_
-3. Enable the {{ api.naming.long_name }} API.
-4. `Setup Authentication.`_
+3. `Enable the {{ api.naming.title }}.`_
+4. `Set up Authentication.`_
 
 .. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
 .. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
-.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html
+.. _Enable the {{ api.naming.title }}.:  {{ api.naming.documentation_uri }}
+.. _Set up Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html
 
 Installation
 ~~~~~~~~~~~~
 
-Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
-create isolated Python environments. The basic problem it addresses is one of
-dependencies and versions, and indirectly permissions.
+Install this library in a virtual environment using `venv`_. `venv`_ is a tool that
+creates isolated Python environments. These isolated environments can have separate
+versions of Python packages, which allows you to isolate one project's dependencies
+from the dependencies of other projects.
 
-With `virtualenv`_, it's possible to install this library without needing system
+With `venv`_, it's possible to install this library without needing system
 install permissions, and without clashing with the installed system
 dependencies.
 
-.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
+.. _`venv`: https://docs.python.org/3/library/venv.html
+
+
+Code samples and snippets
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Code samples and snippets live in the `samples/`_ folder.
+
+.. _samples/: https://github.com/googleapis/google-cloud-python/tree/main/packages/{{ api.naming.warehouse_package_name }}/samples
+
+
+Supported Python Versions
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of
+Python.
+
+Python >= 3.7
+
+.. _active: https://devguide.python.org/devcycle/#in-development-main-branch
+.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches
 
+Unsupported Python Versions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Python <= 3.6
+
+If you are using an `end-of-life`_
+version of Python, we recommend that you update as soon as possible to an actively supported version.
+
+.. _end-of-life: https://devguide.python.org/devcycle/#end-of-life-branches
 
 Mac/Linux
 ^^^^^^^^^
@@ -36,18 +88,30 @@ Mac/Linux
 
     python3 -m venv <your-env>
     source <your-env>/bin/activate
-    <your-env>/bin/pip install /path/to/library
+    pip install {{ api.naming.warehouse_package_name }}
 
 
 Windows
 ^^^^^^^
 
 .. code-block:: console
 
-    python3 -m venv <your-env>
-    <your-env>\Scripts\activate
-    <your-env>\Scripts\pip.exe install \path\to\library
+    py -m venv <your-env>
+    .\<your-env>\Scripts\activate
+    pip install {{ api.naming.warehouse_package_name }}
+
+Next Steps
+~~~~~~~~~~
 
+-  Read the `Client Library Documentation`_ for {{ api.naming.title }}
+   to see other available methods on the client.
+-  Read the `{{ api.naming.title }} Product documentation`_ to learn
+   more about the product and see How-to Guides.
+-  View this `README`_ to see the full list of Cloud
+   APIs that we cover.
+
+.. _{{ api.naming.title }} Product documentation:  {{ api.naming.documentation_uri }}
+.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst
 
 Logging
 -------
@@ -59,7 +123,6 @@ Note the following:
 #. Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability of the logging events**.
 #. By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below.
 
-
 Simple, environment-based configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -75,9 +138,8 @@ A logging scope is a period-separated namespace that begins with :code:`google`,
 
 **NOTE**: If the logging scope is invalid, the library does not set up any logging handlers.
 
-
-Examples
-^^^^^^^^
+Environment-Based Examples
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - Enabling the default handler for all Google-based loggers
 
@@ -97,18 +159,17 @@ Advanced, code-based configuration
 
 You can also configure a valid logging scope using Python's standard `logging` mechanism.
 
-
-Examples
-^^^^^^^^
+Code-Based Examples
+^^^^^^^^^^^^^^^^^^^
 
 - Configuring a handler for all Google-based loggers
 
 .. code-block:: python
 
     import logging
-    
-    from google.cloud.translate_v3 import translate
-    
+
+    from google.cloud import library_v1
+
     base_logger = logging.getLogger("google")
     base_logger.addHandler(logging.StreamHandler())
     base_logger.setLevel(logging.DEBUG)
@@ -118,14 +179,13 @@ Examples
 .. code-block:: python
 
     import logging
-    
-    from google.cloud.translate_v3 import translate
-    
+
+    from google.cloud import library_v1
+
     base_logger = logging.getLogger("google.cloud.library_v1")
     base_logger.addHandler(logging.StreamHandler())
     base_logger.setLevel(logging.DEBUG)
 
-
 Logging details
 ~~~~~~~~~~~~~~~
 

gapic/templates/docs/README.rst.j2

@@ -0,0 +1 @@
+../README.rst.j2

gapic/templates/docs/index.rst.j2

@@ -1,3 +1,5 @@
+.. include:: README.rst
+
 .. include:: multiprocessing.rst
 
 
@@ -8,3 +10,21 @@ API Reference
 
     {{ api.naming.versioned_module_name }}/services_
     {{ api.naming.versioned_module_name }}/types_
+
+
+Changelog
+---------
+
+For a list of all ``{{ api.naming.warehouse_package_name }}`` releases:
+
+.. toctree::
+    :maxdepth: 2
+
+    CHANGELOG
+
+.. toctree::
+  :hidden:
+{% if api.naming.module_namespace|length >= 2 and api.naming.module_namespace[0] == "google" and api.naming.module_namespace[1] == "cloud" %}
+
+  summary_overview.md
+{% endif %}

gapic/templates/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, create an
+"overview_content.md" file in `docs/` directory. The Sphinx tool will
+pick up on the content and merge the content.
+]: #
+
+# {{ api.naming.title }}
+
+Overview of the APIs available for {{ api.naming.title }}.
+
+## All entries
+
+Classes, methods and properties & attributes for
+{{ api.naming.title }}.
+
+[classes](https://cloud.google.com/python/docs/reference/{{ api.naming.documentation_name }}/latest/summary_class.html)
+
+[methods](https://cloud.google.com/python/docs/reference/{{ api.naming.documentation_name }}/latest/summary_method.html)
+
+[properties and
+attributes](https://cloud.google.com/python/docs/reference/{{ api.naming.documentation_name }}/latest/summary_property.html)

gapic/utils/options.py

@@ -50,6 +50,11 @@ class Options:
     service_yaml_config: Dict[str, Any] = dataclasses.field(default_factory=dict)
     rest_numeric_enums: bool = False
     proto_plus_deps: Tuple[str, ...] = dataclasses.field(default=("",))
+    api_description: str = ""
+    documentation_name: str = ""
+    documentation_uri: str = ""
+    release_level: str = ""
+    title: str = ""
 
     # Class constants
     PYTHON_GAPIC_PREFIX: str = "python-gapic-"
@@ -71,6 +76,8 @@ class Options:
             # proto plus dependencies delineated by '+'
             # For example, 'google.cloud.api.v1+google.cloud.anotherapi.v2'
             "proto-plus-deps",
+            "release-level",  # One of ["preview", "stable"]
+            "documentation-name",
         )
     )
 
@@ -152,6 +159,14 @@ def tweak_path(p):
         # but it is not a field in the gogle.api.Service proto.
         service_yaml_config.pop("type", None)
 
+        api_description = service_yaml_config.get("documentation", {}).get(
+            "summary", ""
+        )
+
+        documentation_uri = service_yaml_config.get("publishing", {}).get(
+            "documentation_uri", ""
+        )
+
         # Build the options instance.
         sample_paths = opts.pop("samples", [])
 
@@ -196,7 +211,14 @@ def tweak_path(p):
             transport=opts.pop("transport", ["grpc"])[0].split("+"),
             service_yaml_config=service_yaml_config,
             rest_numeric_enums=bool(opts.pop("rest-numeric-enums", False)),
+            title=service_yaml_config.get("title", ""),
+            documentation_name=opts.pop("documentation-name", [""]).pop(),
+            documentation_uri=documentation_uri,
+            api_description=api_description,
             proto_plus_deps=proto_plus_deps,
+            release_level=opts.pop(
+                "release-level", ["preview"]
+            ).pop(),  # Default to "preview" unless explicitly set to "stable"
         )
 
         # Note: if we ever need to recursively check directories for sample

tests/integration/cloudasset_v1.yaml

@@ -44,4 +44,13 @@ authentication:
   - selector: google.longrunning.Operations.GetOperation
     oauth:
       canonical_scopes: |-
-        https://www.googleapis.com/auth/cloud-platform
+        https://www.googleapis.com/auth/cloud-platform
+publishing:
+  organization: CLIENT_LIBRARY_ORGANIZATION_UNSPECIFIED
+  new_issue_uri: ''
+  documentation_uri: 'https://cloud.google.com/resource-manager/docs/cloud-asset-inventory/overview'
+  api_short_name: ''
+  github_label: ''
+  doc_tag_prefix: ''
+  codeowner_github_teams:
+  library_settings:

tests/integration/eventarc_v1.yaml

@@ -119,6 +119,13 @@ authentication:
 
 
 publishing:
+  organization: CLIENT_LIBRARY_ORGANIZATION_UNSPECIFIED
+  new_issue_uri: ''
+  documentation_uri: 'https://cloud.google.com/eventarc'
+  api_short_name: ''
+  github_label: ''
+  doc_tag_prefix: ''
+  codeowner_github_teams:
   library_settings:
   - version: 'google.cloud.eventarc.v1'
     python_settings: