docs: update c.g.c docs and guides (#994)

* docs: streamline acl/iam docs

* update docs and guides

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* exclude README from owlbot

* revert owlbot readme reverts

---------

Co-authored-by: Dan Lee <[email protected]>
Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Author: 3 people

README.rst

@@ -1,56 +1,73 @@
-Python Client for Google Cloud Storage API
-==========================================
+Python Client for Google Cloud Storage
+======================================
 
 |stable| |pypi| |versions|
 
-`Google Cloud Storage API`_: is a durable and highly available object storage service. Google Cloud Storage is almost infinitely scalable and guarantees consistency: when a write succeeds, the latest copy of the object will be returned to any GET, globally.
+`Google Cloud Storage`_ is a managed service for storing unstructured data. Cloud Storage
+allows world-wide storage and retrieval of any amount of data at any time. You can use
+Cloud Storage for a range of scenarios including serving website content, storing data
+for archival and disaster recovery, or distributing large data objects to users via direct download.
+
+A comprehensive list of changes in each version may be found in the `CHANGELOG`_.
 
-- `Client Library Documentation`_
 - `Product Documentation`_
+- `Client Library Documentation`_
+- `github.com/googleapis/python-storage`_
+
+Read more about the client libraries for Cloud APIs, including the older
+Google APIs Client Libraries, in `Client Libraries Explained`_.
 
 .. |stable| image:: https://img.shields.io/badge/support-stable-gold.svg
    :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels
 .. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-storage.svg
    :target: https://pypi.org/project/google-cloud-storage/
 .. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-storage.svg
    :target: https://pypi.org/project/google-cloud-storage/
-.. _Google Cloud Storage API: https://cloud.google.com/storage
+.. _Google Cloud Storage: https://cloud.google.com/storage
 .. _Client Library Documentation: https://cloud.google.com/python/docs/reference/storage/latest
 .. _Product Documentation:  https://cloud.google.com/storage
+.. _CHANGELOG:  https://github.com/googleapis/python-storage/blob/main/CHANGELOG.md
+.. _github.com/googleapis/python-storage: https://github.com/googleapis/python-storage
+.. _Client Libraries Explained: https://cloud.google.com/apis/docs/client-libraries-explained
 
 Quick Start
 -----------
 
-In order to use this library, you first need to go through the following steps:
+In order to use this library, you first need to go through the following steps.
+A step-by-step guide may also be found in `Get Started with Client Libraries`_.
 
 1. `Select or create a Cloud Platform project.`_
 2. `Enable billing for your project.`_
 3. `Enable the Google Cloud Storage API.`_
 4. `Setup Authentication.`_
 
+.. _Get Started with Client Libraries: https://cloud.google.com/storage/docs/reference/libraries#client-libraries-install-python
 .. _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
-.. _Enable the Google Cloud Storage API.:  https://cloud.google.com/storage
-.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html
+.. _Enable the Google Cloud Storage API.:  https://console.cloud.google.com/flows/enableapi?apiid=storage-api.googleapis.com
+.. _Setup Authentication.: https://cloud.google.com/docs/authentication/client-libraries
 
 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.
+Code samples and snippets live in the `samples/`_ folder.
+
+.. _`samples/`: https://github.com/googleapis/python-storage/tree/main/samples
 
 
 Supported Python Versions
@@ -77,31 +94,29 @@ Mac/Linux
 
 .. code-block:: console
 
-    pip install virtualenv
-    virtualenv <your-env>
+    python3 -m venv <your-env>
     source <your-env>/bin/activate
-    <your-env>/bin/pip install google-cloud-storage
+    pip install google-cloud-storage
 
 
 Windows
 ^^^^^^^
 
 .. code-block:: console
 
-    pip install virtualenv
-    virtualenv <your-env>
-    <your-env>\Scripts\activate
-    <your-env>\Scripts\pip.exe install google-cloud-storage
+    py -m venv <your-env>
+    .\<your-env>\Scripts\activate
+    pip install google-cloud-storage
 
 Next Steps
 ~~~~~~~~~~
 
+-  Read the `Google Cloud Storage Product documentation`_ to learn
+   more about the product and see How-to Guides.
 -  Read the `Client Library Documentation`_ for Google Cloud Storage API
    to see other available methods on the client.
--  Read the `Google Cloud Storage API 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.
 
-.. _Google Cloud Storage API Product documentation:  https://cloud.google.com/storage
+.. _Google Cloud Storage Product documentation:  https://cloud.google.com/storage
 .. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst

docs/acl_guide.rst

@@ -1,13 +1,22 @@
+Managing Access to Data
+=======================
+
+Cloud Storage offers two systems for granting users access your buckets and objects:
+IAM and Access Control Lists (ACLs). These systems act in parallel - in order for a user to
+access a Cloud Storage resource, only one of the systems needs to grant that user permission.
+For additional access control options, see also:
+`Cloud Storage Control Access to Data <https://cloud.google.com/storage/docs/access-control>`_  
+
+
 ACL
-===
+---
 
 Cloud Storage uses access control lists (ACLs) to manage object and bucket access.
 ACLs are the mechanism you use to share files with other users and allow
 other users to access your buckets and files.
 
 ACLs are suitable for fine-grained control, but you may prefer using IAM to
-control access at the project level. See also:
-`Cloud Storage Control Access to Data <https://cloud.google.com/storage/docs/access-control>`_
+control access at the project level.
 
 
 :class:`google.cloud.storage.bucket.Bucket` has a getting method that creates
@@ -80,3 +89,77 @@ To get the list of ``entity`` and ``role`` for each unique pair, the
 This list of tuples can be used as the ``entity`` and ``role`` fields
 when sending metadata for ACLs to the API.
 
+
+IAM
+---
+
+Identity and Access Management (IAM) controls permissioning throughout Google Cloud and allows you
+to grant permissions at the bucket and project levels. You should use IAM for any permissions that
+apply to multiple objects in a bucket to reduce the risks of unintended exposure. To use IAM
+exclusively, enable uniform bucket-level access to disallow ACLs for all Cloud Storage resources.
+See also:
+`Additional access control options <https://cloud.google.com/storage/docs/access-control#additional_access_control_options>`_ 
+
+Constants used across IAM roles:
+::::::::::::::::::::::::::::::::
+
+- ``STORAGE_OBJECT_CREATOR_ROLE = "roles/storage.objectCreator"``
+  corresponds to role implying rights to create objects, but not delete or overwrite them.
+- ``STORAGE_OBJECT_VIEWER_ROLE = "roles/storage.objectViewer"``
+  corresponds to role implying rights to view object properties, excluding ACLs.
+- ``STORAGE_OBJECT_ADMIN_ROLE = "roles/storage.objectAdmin"``
+  corresponds to role implying full control of objects.
+- ``STORAGE_ADMIN_ROLE = "roles/storage.admin"``
+  corresponds to role implying full control of objects and buckets.
+- ``STORAGE_VIEWER_ROLE = "Viewer"``
+  corresponds to role that can list buckets.
+- ``STORAGE_EDITOR_ROLE = "Editor"``
+  corresponds to role that can create, list, and delete buckets.
+- ``STORAGE_OWNER_ROLE = "Owners"``
+  corresponds to role that can Can create, list, and delete buckets;
+  and list tag bindings; and control HMAC keys in the project.
+
+Constants used across IAM permissions:
+::::::::::::::::::::::::::::::::::::::
+
+- ``STORAGE_BUCKETS_CREATE = "storage.buckets.create"``
+  corresponds to permission that can create buckets.
+
+- ``STORAGE_BUCKETS_DELETE = "storage.buckets.delete"``
+  corresponds to permission that can delete buckets.
+
+- ``STORAGE_BUCKETS_GET = "storage.buckets.get"``
+  corresponds to permission that can read bucket metadata, excluding ACLs.
+
+- ``STORAGE_BUCKETS_LIST = "storage.buckets.list"``
+  corresponds to permission that can list buckets.
+
+- ``STORAGE_BUCKETS_GET_IAM_POLICY = "storage.buckets.getIamPolicy"``
+  corresponds to permission that can read bucket ACLs.
+
+- ``STORAGE_BUCKETS_SET_IAM_POLICY = "storage.buckets.setIamPolicy"``
+  corresponds to permission that can update bucket ACLs.
+
+- ``STORAGE_BUCKETS_UPDATE = "storage.buckets.update"``
+  corresponds to permission that can update buckets, excluding ACLS.
+
+- ``STORAGE_OBJECTS_CREATE = "storage.objects.create"``
+  corresponds to permission that can add new objects to a bucket.
+
+- ``STORAGE_OBJECTS_DELETE = "storage.objects.delete"``
+  corresponds to permission that can delete objects.
+
+- ``STORAGE_OBJECTS_GET = "storage.objects.get"``
+  corresponds to permission that can read object data / metadata, excluding ACLs.
+
+- ``STORAGE_OBJECTS_LIST = "storage.objects.list"``
+  corresponds to permission that can list objects in a bucket.
+
+- ``STORAGE_OBJECTS_GET_IAM_POLICY = "storage.objects.getIamPolicy"``
+  corresponds to permission that can read object ACLs.
+
+- ``STORAGE_OBJECTS_SET_IAM_POLICY = "storage.objects.setIamPolicy"``
+  corresponds to permission that can update object ACLs.
+
+- ``STORAGE_OBJECTS_UPDATE = "storage.objects.update"``
+  corresponds to permission that can update object metadata, excluding ACLs.

google/cloud/storage/constants.py

@@ -12,7 +12,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Constants used across google.cloud.storage modules."""
+"""Constants used across google.cloud.storage modules.
+
+See [Python Storage Client Constants Page](https://github.com/googleapis/python-storage/blob/main/google/cloud/storage/constants.py)
+for constants used across storage classes, location types, public access prevention, etc.
+
+"""
 
 # Storage classes
 

owlbot.py

@@ -45,6 +45,7 @@
         "docs/multiprocessing.rst",
         "noxfile.py",
         "CONTRIBUTING.rst",
+        "README.rst",
         ".kokoro/samples/python3.6", # remove python 3.6 support
         ".github/workflows", # exclude gh actions as credentials are needed for tests
         ".github/release-please.yml", # special support for a python2 branch in this repo