BigQuery: use submodule aliases in docstrings. (#4255)

This allows Sphinx to find the source files for documenting properties/attributes.
googleapis · Oct 25, 2017 · a2efd96 · a2efd96
1 parent 877ef4e
commit a2efd96
Show file tree

Hide file tree

Showing 9 changed files with 213 additions and 167 deletions.
diff --git a/bigquery/google/cloud/bigquery/__init__.py b/bigquery/google/cloud/bigquery/__init__.py
@@ -16,6 +16,11 @@
 
 The main concepts with this API are:
 
+- :class:`~google.cloud.bigquery.client.Client` manages connections to the
+  BigQuery API. Use the client methods to run jobs (such as a
+  :class:`~google.cloud.bigquery.job.QueryJob` via
+  :meth:`~google.cloud.bigquery.client.Client.query`) and manage resources.
+
 - :class:`~google.cloud.bigquery.dataset.Dataset` represents a
   collection of tables.
 

diff --git a/bigquery/google/cloud/bigquery/client.py b/bigquery/google/cloud/bigquery/client.py
diff --git a/bigquery/google/cloud/bigquery/dataset.py b/bigquery/google/cloud/bigquery/dataset.py
@@ -146,7 +146,7 @@ def table(self, table_id):
         :type table_id: str
         :param table_id: the ID of the table.
 
-        :rtype: :class:`google.cloud.bigquery.TableReference`
+        :rtype: :class:`google.cloud.bigquery.table.TableReference`
         :returns: a TableReference for a table in this dataset.
         """
         return TableReference(self, table_id)
@@ -197,7 +197,7 @@ class Dataset(object):
     See
     https://cloud.google.com/bigquery/docs/reference/rest/v2/datasets
 
-    :type dataset_ref: :class:`~google.cloud.bigquery.DatasetReference`
+    :type dataset_ref: :class:`~google.cloud.bigquery.dataset.DatasetReference`
     :param dataset_ref: a pointer to a dataset
     """
 
@@ -238,7 +238,8 @@ def access_entries(self):
     def access_entries(self, value):
         """Update dataset's access entries
 
-        :type value: list of :class:`~google.cloud.bigquery.AccessEntry`
+        :type value:
+            list of :class:`~google.cloud.bigquery.dataset.AccessEntry`
         :param value: roles granted to entities for this dataset
 
         :raises: TypeError if 'value' is not a sequence, or ValueError if
@@ -401,8 +402,9 @@ def labels(self):
         """Labels for the dataset.
 
         This method always returns a dict. To change a dataset's labels,
-        modify the dict, then call ``Client.update_dataset``. To delete a
-        label, set its value to ``None`` before updating.
+        modify the dict, then call
+        :meth:`google.cloud.bigquery.client.Client.update_dataset`. To delete
+        a label, set its value to ``None`` before updating.
 
         :rtype: dict, {str -> str}
         :returns: A dict of the the dataset's labels.
@@ -429,7 +431,7 @@ def from_api_repr(cls, resource):
         :type resource: dict
         :param resource: dataset resource representation returned from the API
 
-        :rtype: :class:`~google.cloud.bigquery.Dataset`
+        :rtype: :class:`~google.cloud.bigquery.dataset.Dataset`
         :returns: Dataset parsed from ``resource``.
         """
         dsr = resource.get('datasetReference')
@@ -451,7 +453,7 @@ def _parse_access_entries(access):
         :type access: list of mappings
         :param access: each mapping represents a single access entry.
 
-        :rtype: list of :class:`~google.cloud.bigquery.AccessEntry`
+        :rtype: list of :class:`~google.cloud.bigquery.dataset.AccessEntry`
         :returns: a list of parsed entries.
         :raises: :class:`ValueError` if a entry in ``access`` has more keys
                  than ``role`` and one additional key.
@@ -530,7 +532,7 @@ def table(self, table_id):
         :type table_id: str
         :param table_id: the ID of the table.
 
-        :rtype: :class:`~google.cloud.bigquery.TableReference`
+        :rtype: :class:`~google.cloud.bigquery.table.TableReference`
         :returns: a TableReference for a table in this dataset.
         """
         return TableReference(self, table_id)
diff --git a/bigquery/google/cloud/bigquery/external_config.py b/bigquery/google/cloud/bigquery/external_config.py
@@ -177,7 +177,7 @@ def from_api_repr(cls, resource):
             from the API.
 
         :rtype:
-            :class:`~google.cloud.bigquery.BigtableColumnFamily`
+            :class:`~google.cloud.bigquery.external_config.BigtableColumnFamily`
         :returns: Configuration parsed from ``resource``.
         """
         config = cls()
@@ -239,7 +239,8 @@ def from_api_repr(cls, resource):
             A BigtableOptions in the same representation as is returned
             from the API.
 
-        :rtype: :class:`~google.cloud.bigquery.BigtableOptions`
+        :rtype:
+            :class:`~google.cloud.bigquery.external_config.BigtableOptions`
         :returns: Configuration parsed from ``resource``.
         """
         config = cls()
@@ -321,7 +322,7 @@ def from_api_repr(cls, resource):
             A CSVOptions in the same representation as is
             returned from the API.
 
-        :rtype: :class:`~google.cloud.bigquery.CSVOptions`
+        :rtype: :class:`~google.cloud.bigquery.external_config.CSVOptions`
         :returns: Configuration parsed from ``resource``.
         """
         slr = resource.get('skipLeadingRows')
@@ -369,7 +370,7 @@ def from_api_repr(cls, resource):
             returned from the API.
 
         :rtype:
-            :class:`~google.cloud.bigquery.GoogleSheetsOptions`
+            :class:`~google.cloud.bigquery.external_config.GoogleSheetsOptions`
         :returns: Configuration parsed from ``resource``.
         """
         slr = resource.get('skipLeadingRows')
@@ -476,7 +477,7 @@ def from_api_repr(cls, resource):
             An extract job configuration in the same representation as is
             returned from the API.
 
-        :rtype: :class:`~google.cloud.bigquery.CSVOptions`
+        :rtype: :class:`~google.cloud.bigquery.external_config.CSVOptions`
         :returns: Configuration parsed from ``resource``.
         """
         config = cls(resource['sourceFormat'])