diff --git a/gapic/templates/README.rst.j2 b/gapic/templates/README.rst.j2 index 3e6b3746d4..5144bfb912 100644 --- a/gapic/templates/README.rst.j2 +++ b/gapic/templates/README.rst.j2 @@ -1,5 +1,22 @@ Python Client for {{ api.naming.long_name }} API -================================================= +=================={% for i in range(api.naming.long_name|length) %}={% endfor %} + +|preview| |pypi| |versions| + +`{{ metadata['repo']['name_pretty'] }}`_: {% if metadata['repo']['api_description'] %}{{metadata['repo']['api_description'] }}{% endif %} + +- `Client Library Documentation`_ +- `Product Documentation`_ + +.. |preview| image:: https://img.shields.io/badge/support-{{ metadata['repo']['release_level'] }}-{% if metadata['repo']['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/{{ metadata['repo']['distribution_name'] }}.svg + :target: https://pypi.org/project/{{ metadata['repo']['distribution_name'] }}/ +.. |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'] }}: https://cloud.google.com +.. _Client Library Documentation: {{ metadata['repo']['client_documentation'] }} +.. _Product Documentation: https://cloud.google.com Quick Start ----------- @@ -8,26 +25,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.long_name }} API.`_ +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.long_name }} API.: https://cloud.google.com +.. _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/{{ metadata['repo']['distribution_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,7 +82,7 @@ Mac/Linux python3 -m venv source /bin/activate - /bin/pip install /path/to/library + pip install {{ api.naming.warehouse_package_name }} Windows @@ -44,10 +90,22 @@ Windows .. code-block:: console - python3 -m venv - \Scripts\activate - \Scripts\pip.exe install \path\to\library + py -m venv + .\\Scripts\activate + pip install {{ api.naming.warehouse_package_name }} + +Next Steps +~~~~~~~~~~ +- Read the `Client Library Documentation`_ for {{ api.naming.long_name }} + to see other available methods on the client. +- Read the `{{ api.naming.long_name }} 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.long_name }} Product documentation: https://cloud.google.com +.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst Logging ------- @@ -59,7 +117,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 +132,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,9 +153,8 @@ 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 @@ -107,7 +162,7 @@ Examples 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()) @@ -119,13 +174,12 @@ Examples 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 ~~~~~~~~~~~~~~~