Normalize docstring class refs. (#8102)

FBO Sphinx (missing ref links), static analysis, autocompletion.

Also, document 'v1' entities, rather than 'v1beta1'.

Closes #8035.

firestore/docs/batch.rst

@@ -1,6 +1,6 @@
 Batches
 ~~~~~~~
 
-.. automodule:: google.cloud.firestore_v1beta1.batch
+.. automodule:: google.cloud.firestore_v1.batch
   :members:
   :show-inheritance:

firestore/docs/client.rst

@@ -1,6 +1,6 @@
 Client
 ~~~~~~
 
-.. automodule:: google.cloud.firestore_v1beta1.client
+.. automodule:: google.cloud.firestore_v1.client
   :members:
   :show-inheritance:

firestore/docs/collection.rst

@@ -1,6 +1,6 @@
 Collections
 ~~~~~~~~~~~
 
-.. automodule:: google.cloud.firestore_v1beta1.collection
+.. automodule:: google.cloud.firestore_v1.collection
   :members:
   :show-inheritance:

firestore/docs/document.rst

@@ -1,6 +1,6 @@
 Documents
 ~~~~~~~~~
 
-.. automodule:: google.cloud.firestore_v1beta1.document
+.. automodule:: google.cloud.firestore_v1.document
   :members:
   :show-inheritance:

firestore/docs/field_path.rst

@@ -1,7 +1,7 @@
 Field Paths
 ~~~~~~~~~~~
 
-.. automodule:: google.cloud.firestore_v1beta1.field_path
+.. automodule:: google.cloud.firestore_v1.field_path
   :members:
   :show-inheritance:
 

firestore/docs/query.rst

@@ -1,6 +1,6 @@
 Queries
 ~~~~~~~
 
-.. automodule:: google.cloud.firestore_v1beta1.query
+.. automodule:: google.cloud.firestore_v1.query
   :members:
   :show-inheritance:

firestore/docs/transaction.rst

@@ -1,7 +1,7 @@
 Transactions
 ~~~~~~~~~~~~
 
-.. automodule:: google.cloud.firestore_v1beta1.transaction
+.. automodule:: google.cloud.firestore_v1.transaction
   :inherited-members:
   :members:
   :show-inheritance:

firestore/docs/transforms.rst

@@ -1,6 +1,6 @@
 Transforms
 ~~~~~~~~~~
 
-.. automodule:: google.cloud.firestore_v1beta1.transforms
+.. automodule:: google.cloud.firestore_v1.transforms
   :members:
   :show-inheritance:

firestore/docs/types.rst

@@ -1,6 +1,6 @@
 Types
 ~~~~~
 
-.. automodule:: google.cloud.firestore_v1beta1.types
+.. automodule:: google.cloud.firestore_v1.types
   :members:
   :show-inheritance:

firestore/google/cloud/firestore_v1/_helpers.py

@@ -220,12 +220,12 @@ def reference_value_to_document(reference_value, client):
 
     Args:
         reference_value (str): A document reference value.
-        client (~.firestore_v1.client.Client): A client that has
-            a document factory.
+        client (:class:`~google.cloud.firestore_v1.client.Client`):
+            A client that has a document factory.
 
     Returns:
-        ~.firestore_v1.document.DocumentReference: The document
-        corresponding to ``reference_value``.
+        :class:`~google.cloud.firestore_v1.document.DocumentReference`:
+            The document corresponding to ``reference_value``.
 
     Raises:
         ValueError: If the ``reference_value`` is not of the expected
@@ -255,8 +255,8 @@ def decode_value(value, client):
     Args:
         value (google.cloud.firestore_v1.types.Value): A
             Firestore protobuf to be decoded / parsed / converted.
-        client (~.firestore_v1.client.Client): A client that has
-            a document factory.
+        client (:class:`~google.cloud.firestore_v1.client.Client`):
+            A client that has a document factory.
 
     Returns:
         Union[NoneType, bool, int, float, datetime.datetime, \
@@ -301,8 +301,8 @@ def decode_dict(value_fields, client):
     Args:
         value_fields (google.protobuf.pyext._message.MessageMapContainer): A
             protobuf map of Firestore ``Value``-s.
-        client (~.firestore_v1.client.Client): A client that has
-            a document factory.
+        client (:class:`~google.cloud.firestore_v1.client.Client`):
+            A client that has a document factory.
 
     Returns:
         Dict[str, Union[NoneType, bool, int, float, datetime.datetime, \
@@ -851,9 +851,9 @@ def pbs_for_update(document_path, field_updates, option):
         document_path (str): A fully-qualified document path.
         field_updates (dict): Field names or paths to update and values
             to update with.
-        option (optional[~.firestore_v1.client.WriteOption]): A
-           write option to make assertions / preconditions on the server
-           state of the document before applying changes.
+        option (optional[:class:`~google.cloud.firestore_v1.client.WriteOption`]):
+            A write option to make assertions / preconditions on the server
+            state of the document before applying changes.
 
     Returns:
         List[google.cloud.firestore_v1.types.Write]: One
@@ -890,9 +890,9 @@ def pb_for_delete(document_path, option):
 
     Args:
         document_path (str): A fully-qualified document path.
-        option (optional[~.firestore_v1.client.WriteOption]): A
-           write option to make assertions / preconditions on the server
-           state of the document before applying changes.
+        option (optional[:class:`~google.cloud.firestore_v1.client.WriteOption`]):
+            A write option to make assertions / preconditions on the server
+            state of the document before applying changes.
 
     Returns:
         google.cloud.firestore_v1.types.Write: A
@@ -916,9 +916,9 @@ def get_transaction_id(transaction, read_operation=True):
     """Get the transaction ID from a ``Transaction`` object.
 
     Args:
-        transaction (Optional[~.firestore_v1.transaction.\
-            Transaction]): An existing transaction that this query will
-            run in.
+        transaction (Optional[:class:`~google.cloud.firestore_v1.transaction.\
+            Transaction`]):
+            An existing transaction that this query will run in.
         read_operation (Optional[bool]): Indicates if the transaction ID
             will be used in a read operation. Defaults to :data:`True`.
 
@@ -979,7 +979,7 @@ class LastUpdateOption(WriteOption):
     """Option used to assert a "last update" condition on a write operation.
 
     This will typically be created by
-    :meth:`~.firestore_v1.client.Client.write_option`.
+    :meth:`~google.cloud.firestore_v1.client.Client.write_option`.
 
     Args:
         last_update_time (google.protobuf.timestamp_pb2.Timestamp): A
@@ -1019,7 +1019,7 @@ class ExistsOption(WriteOption):
     """Option used to assert existence on a write operation.
 
     This will typically be created by
-    :meth:`~.firestore_v1.client.Client.write_option`.
+    :meth:`~google.cloud.firestore_v1.client.Client.write_option`.
 
     Args:
         exists (bool): Indicates if the document being modified

firestore/google/cloud/firestore_v1/batch.py

@@ -22,12 +22,12 @@ class WriteBatch(object):
     """Accumulate write operations to be sent in a batch.
 
     This has the same set of methods for write operations that
-    :class:`~.firestore_v1.document.DocumentReference` does,
-    e.g. :meth:`~.firestore_v1.document.DocumentReference.create`.
+    :class:`~google.cloud.firestore_v1.document.DocumentReference` does,
+    e.g. :meth:`~google.cloud.firestore_v1.document.DocumentReference.create`.
 
     Args:
-        client (~.firestore_v1.client.Client): The client that
-            created this batch.
+        client (:class:`~google.cloud.firestore_v1.client.Client`):
+            The client that created this batch.
     """
 
     def __init__(self, client):
@@ -54,8 +54,8 @@ def create(self, reference, document_data):
         batch will fail when :meth:`commit`-ed.
 
         Args:
-            reference (~.firestore_v1.document.DocumentReference): A
-                document reference to be created in this batch.
+            reference (:class:`~google.cloud.firestore_v1.document.DocumentReference`):
+                A document reference to be created in this batch.
             document_data (dict): Property names and values to use for
                 creating a document.
         """
@@ -66,12 +66,12 @@ def set(self, reference, document_data, merge=False):
         """Add a "change" to replace a document.
 
         See
-        :meth:`~.firestore_v1.document.DocumentReference.set` for
+        :meth:`google.cloud.firestore_v1.document.DocumentReference.set` for
         more information on how ``option`` determines how the change is
         applied.
 
         Args:
-            reference (~.firestore_v1.document.DocumentReference):
+            reference (:class:`~google.cloud.firestore_v1.document.DocumentReference`):
                 A document reference that will have values set in this batch.
             document_data (dict):
                 Property names and values to use for replacing a document.
@@ -94,17 +94,17 @@ def update(self, reference, field_updates, option=None):
         """Add a "change" to update a document.
 
         See
-        :meth:`~.firestore_v1.document.DocumentReference.update` for
-        more information on ``field_updates`` and ``option``.
+        :meth:`google.cloud.firestore_v1.document.DocumentReference.update`
+        for more information on ``field_updates`` and ``option``.
 
         Args:
-            reference (~.firestore_v1.document.DocumentReference): A
-               document reference that will be deleted in this batch.
-            field_updates (dict): Field names or paths to update and values
-                to update with.
-            option (Optional[~.firestore_v1.client.WriteOption]): A
-               write option to make assertions / preconditions on the server
-               state of the document before applying changes.
+            reference (:class:`~google.cloud.firestore_v1.document.DocumentReference`):
+                A document reference that will be updated in this batch.
+            field_updates (dict):
+                Field names or paths to update and values to update with.
+            option (Optional[:class:`~google.cloud.firestore_v1.client.WriteOption`]):
+                A write option to make assertions / preconditions on the server
+                state of the document before applying changes.
         """
         if option.__class__.__name__ == "ExistsOption":
             raise ValueError("you must not pass an explicit write option to " "update.")
@@ -117,16 +117,16 @@ def delete(self, reference, option=None):
         """Add a "change" to delete a document.
 
         See
-        :meth:`~.firestore_v1.document.DocumentReference.delete` for
-        more information on how ``option`` determines how the change is
+        :meth:`google.cloud.firestore_v1.document.DocumentReference.delete`
+        for more information on how ``option`` determines how the change is
         applied.
 
         Args:
-            reference (~.firestore_v1.document.DocumentReference): A
-               document reference that will be deleted in this batch.
-            option (Optional[~.firestore_v1.client.WriteOption]): A
-               write option to make assertions / preconditions on the server
-               state of the document before applying changes.
+            reference (:class:`~google.cloud.firestore_v1.document.DocumentReference`):
+                A document reference that will be deleted in this batch.
+            option (Optional[:class:`~google.cloud.firestore_v1.client.WriteOption`]):
+                A write option to make assertions / preconditions on the server
+                state of the document before applying changes.
         """
         write_pb = _helpers.pb_for_delete(reference._document_path, option)
         self._add_write_pbs([write_pb])
@@ -135,11 +135,10 @@ def commit(self):
         """Commit the changes accumulated in this batch.
 
         Returns:
-            List[google.cloud.proto.firestore.v1.\
-                write_pb2.WriteResult, ...]: The write results corresponding
-            to the changes committed, returned in the same order as the
-            changes were applied to this batch. A write result contains an
-            ``update_time`` field.
+            List[:class:`google.cloud.proto.firestore.v1.write_pb2.WriteResult`, ...]:
+            The write results corresponding to the changes committed, returned
+            in the same order as the changes were applied to this batch. A
+            write result contains an ``update_time`` field.
         """
         commit_response = self._client._firestore_api.commit(
             self._client._database_string,