docs: sync README with synthtool templates

gapic/generator/generator.py

@@ -269,11 +269,19 @@ def _render_template(
         # library. This means that the module names will need to be versioned in
         # import statements. For example `import google.cloud.library_v2` instead
         # of `import google.cloud.library`.
+        # If default version is specified, and doesn't match the current version being generated or
+        # `python_settings.experimental_features.unversioned_package_disabled` is set
         if (
-            template_name.startswith("%namespace/%name/")
-            and api_schema.all_library_settings[
-                api_schema.naming.proto_package
-            ].python_settings.experimental_features.unversioned_package_disabled
+            (
+                template_name.startswith("%namespace/%name/")
+                and api_schema.all_library_settings[
+                    api_schema.naming.proto_package
+                ].python_settings.experimental_features.unversioned_package_disabled
+             ) or
+             (
+                 len(opts.default_version) > 0 and
+                 opts.default_version != api_schema.naming.version
+             )
         ):
             return answer
 

gapic/schema/naming.py

@@ -45,6 +45,13 @@ class Naming(abc.ABC):
     proto_package: str = ""
     _warehouse_package_name: str = ""
     proto_plus_deps: Tuple[str, ...] = dataclasses.field(default_factory=tuple)
+    non_default_versions: Tuple[str, ...] = dataclasses.field(default_factory=tuple)
+    api_description: str = ""
+    default_version: str = ""
+    _documentation_name: str = ""
+    documentation_uri: str = ""
+    release_level: str = ""
+    title: str = ""
 
     def __post_init__(self):
         if not self.product_name:
@@ -154,6 +161,40 @@ def build(
             package_info = dataclasses.replace(
                 package_info, _warehouse_package_name=opts.warehouse_package_name
             )
+
+        if opts.non_default_versions:
+            package_info = dataclasses.replace(
+                package_info, non_default_versions=opts.non_default_versions
+            )
+
+        if opts.api_description:
+            package_info = dataclasses.replace(
+                package_info, api_description=opts.api_description
+            )
+
+        if opts.default_version:
+            package_info = dataclasses.replace(
+                package_info, default_version=opts.default_version
+            )
+
+        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 +253,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,29 @@ API Reference
 
     {{ api.naming.versioned_module_name }}/services_
     {{ api.naming.versioned_module_name }}/types_
+{% for api_version in api.naming.non_default_versions %}
+API Reference
+-------------
+.. toctree::
+    :maxdepth: 2
+
+    {{ api_version }}/services_
+    {{ api_version }}/types_
+{% endfor %}
+
+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)