Merge pull request #1345 from dhermes/some-docs-cleanup

Fixing some docstrings that did not render as intended

Author: dhermes

docs/dns-resource_record_set.rst docs/dns-resource-record-set.rstdocs/dns-resource_record_set.rst renamed to docs/dns-resource-record-set.rst

@@ -67,7 +67,7 @@
   dns-usage
   Client <dns-client>
   dns-zone
-  dns-resource_record_set
+  dns-resource-record-set
   dns-changes
 
 .. toctree::
@@ -115,7 +115,7 @@ try installing the ``dev`` packages beforehand:
 
     $ sudo apt-get install python-dev libssl-dev
 
-If you want to install `gcloud-python` from source,
+If you want to install ``gcloud-python`` from source,
 you can clone the repository from GitHub:
 
 .. code-block:: console

docs/index.rst

@@ -151,11 +151,15 @@ def list_jobs(self, max_results=None, page_token=None, all_users=None,
 
         :type state_filter: string
         :param state_filter: if passed, include only jobs matching the given
-                             state.  One of "done", "pending", or "running".
+                             state.  One of
+
+                             * ``"done"``
+                             * ``"pending"``
+                             * ``"running"``
 
         :rtype: tuple, (list, str)
         :returns: list of job instances, plus a "next page token" string:
-                  if the token is not None, indicates that more jobs can be
+                  if the token is not ``None``, indicates that more jobs can be
                   retrieved with another call, passing that value as
                   ``page_token``).
         """

gcloud/bigquery/client.py

@@ -23,12 +23,19 @@
 class AccessGrant(object):
     """Represent grant of an access role to an entity.
 
-    :type role: string (one of 'OWNER', 'WRITER', 'READER').
-    :param role: role granted to the entity.
+    :type role: string
+    :param role: Role granted to the entity. One of
 
-    :type entity_type: string (one of 'specialGroup', 'groupByEmail', or
-                       'userByEmail')
-    :param entity_type: type of entity being granted the role.
+                 * ``'OWNER'``
+                 * ``'WRITER'``
+                 * ``'READER'``
+
+    :type entity_type: string
+    :param entity_type: Type of entity being granted the role. One of
+
+                        * ``'specialGroup'``
+                        * ``'groupByEmail'``
+                        * ``'userByEmail'``
 
     :type entity_id: string
     :param entity_id: ID of entity being granted the role.
@@ -360,7 +367,7 @@ def create(self, client=None):
         """API call:  create the dataset via a PUT request
 
         See:
-        https://cloud.google.com/bigquery/reference/rest/v2/tables/insert
+        https://cloud.google.com/bigquery/docs/reference/v2/tables/insert
 
         :type client: :class:`gcloud.bigquery.client.Client` or ``NoneType``
         :param client: the client to use.  If not passed, falls back to the
@@ -465,7 +472,7 @@ def delete(self, client=None):
         """API call:  delete the dataset via a DELETE request
 
         See:
-        https://cloud.google.com/bigquery/reference/rest/v2/datasets/delete
+        https://cloud.google.com/bigquery/docs/reference/v2/tables/delete
 
         :type client: :class:`gcloud.bigquery.client.Client` or ``NoneType``
         :param client: the client to use.  If not passed, falls back to the
@@ -491,7 +498,7 @@ def list_tables(self, max_results=None, page_token=None):
 
         :rtype: tuple, (list, str)
         :returns: list of :class:`gcloud.bigquery.table.Table`, plus a
-                  "next page token" string:  if not None, indicates that
+                  "next page token" string:  if not ``None``, indicates that
                   more tables can be retrieved with another call (pass that
                   value as ``page_token``).
         """

gcloud/bigquery/dataset.py

@@ -192,9 +192,10 @@ def delete(self):
     def list_column_families(self):
         """List the column families owned by this table.
 
-        :rtype: dictionary with string as keys and
-                :class:`.column_family.ColumnFamily` as values
-        :returns: List of column families attached to this table.
+        :rtype: dict
+        :returns: Dictionary of column families attached to this table. Keys
+                  are strings (column family names) and values are
+                  :class:`.column_family.ColumnFamily` instances.
         :raises: :class:`ValueError <exceptions.ValueError>` if the column
                  family name from the response does not agree with the computed
                  name from the column family ID.

gcloud/bigtable/table.py

@@ -46,12 +46,12 @@ def from_service_account_json(cls, json_credentials_path, *args, **kwargs):
         :type args: tuple
         :param args: Remaining positional arguments to pass to constructor.
 
-        :type kwargs: dictionary
+        :type kwargs: dict
         :param kwargs: Remaining keyword arguments to pass to constructor.
 
         :rtype: :class:`gcloud.pubsub.client.Client`
         :returns: The client created with the retrieved JSON credentials.
-        :raises: class:`TypeError` if there is a conflict with the kwargs
+        :raises: :class:`TypeError` if there is a conflict with the kwargs
                  and the credentials created by the factory.
         """
         if 'credentials' in kwargs:
@@ -80,12 +80,12 @@ def from_service_account_p12(cls, client_email, private_key_path,
         :type args: tuple
         :param args: Remaining positional arguments to pass to constructor.
 
-        :type kwargs: dictionary
+        :type kwargs: dict
         :param kwargs: Remaining keyword arguments to pass to constructor.
 
         :rtype: :class:`gcloud.client.Client`
         :returns: The client created with the retrieved P12 credentials.
-        :raises: class:`TypeError` if there is a conflict with the kwargs
+        :raises: :class:`TypeError` if there is a conflict with the kwargs
                  and the credentials created by the factory.
         """
         if 'credentials' in kwargs:

gcloud/client.py

@@ -124,15 +124,18 @@ class JSONConnection(Connection):
     """A connection to a Google JSON-based API.
 
     These APIs are discovery based. For reference:
+
         https://developers.google.com/discovery/
 
-    This defines :meth:`Connection.api_request` for making a generic JSON
+    This defines :meth:`api_request` for making a generic JSON
     API request and API requests are created elsewhere.
 
     The class constants
-    * ``API_BASE_URL``
-    * ``API_VERSION``
-    * ``API_URL_TEMPLATE``
+
+    * :attr:`API_BASE_URL`
+    * :attr:`API_VERSION`
+    * :attr:`API_URL_TEMPLATE`
+
     must be updated by subclasses.
     """
 
@@ -303,12 +306,12 @@ def api_request(self, method, path, query_params=None,
                             latest API version supported by
                             gcloud-python.
 
-        :type expect_json: boolean
+        :type expect_json: bool
         :param expect_json: If True, this method will try to parse the
                             response as JSON and raise an exception if
                             that cannot be done.  Default is True.
 
-        :type _target_object: object or :class:`NoneType`
+        :type _target_object: :class:`object` or :class:`NoneType`
         :param _target_object: Protected argument to be used by library
                                callers. This can allow custom behavior, for
                                example, to defer an HTTP request and complete

gcloud/connection.py

@@ -46,38 +46,51 @@ def get_credentials():
     """Gets credentials implicitly from the current environment.
 
     .. note::
-      You should not need to use this function directly. Instead, use the
-      helper method :func:`gcloud.datastore.__init__.get_connection`
-      which uses this method under the hood.
+
+        You should not need to use this function directly. Instead, use a
+        helper method which uses this method under the hood.
 
     Checks environment in order of precedence:
 
     * Google App Engine (production and testing)
-    * Environment variable GOOGLE_APPLICATION_CREDENTIALS pointing to
+    * Environment variable :envvar:`GOOGLE_APPLICATION_CREDENTIALS` pointing to
       a file with stored credentials information.
     * Stored "well known" file associated with ``gcloud`` command line tool.
     * Google Compute Engine production environment.
 
-    The file referred to in GOOGLE_APPLICATION_CREDENTIALS is expected to
-    contain information about credentials that are ready to use. This means
-    either service account information or user account information with
-    a ready-to-use refresh token::
+    The file referred to in :envvar:`GOOGLE_APPLICATION_CREDENTIALS` is
+    expected to contain information about credentials that are ready to use.
+    This means either service account information or user account information
+    with a ready-to-use refresh token:
+
+    .. code:: json
+
+      {
+          'type': 'authorized_user',
+          'client_id': '...',
+          'client_secret': '...',
+          'refresh_token': '...'
+      }
 
-      {                                       {
-          'type': 'authorized_user',              'type': 'service_account',
-          'client_id': '...',                     'client_id': '...',
-          'client_secret': '...',       OR        'client_email': '...',
-          'refresh_token': '...,                  'private_key_id': '...',
-      }                                           'private_key': '...',
-                                              }
+    or
+
+    .. code:: json
+
+      {
+          'type': 'service_account',
+          'client_id': '...',
+          'client_email': '...',
+          'private_key_id': '...',
+          'private_key': '...'
+      }
 
     The second of these is simply a JSON key downloaded from the Google APIs
     console. The first is a close cousin of the "client secrets" JSON file
-    used by ``oauth2client.clientsecrets`` but differs in formatting.
+    used by :mod:`oauth2client.clientsecrets` but differs in formatting.
 
     :rtype: :class:`oauth2client.client.GoogleCredentials`,
-            :class:`oauth2client.appengine.AppAssertionCredentials`,
-            :class:`oauth2client.gce.AppAssertionCredentials`,
+            :class:`oauth2client.contrib.appengine.AppAssertionCredentials`,
+            :class:`oauth2client.contrib.gce.AppAssertionCredentials`,
             :class:`oauth2client.service_account._ServiceAccountCredentials`
     :returns: A new credentials instance corresponding to the implicit
               environment.
@@ -119,7 +132,7 @@ def get_for_service_account_p12(client_email, private_key_path, scope=None):
 
     .. note::
       This method is not used by default, instead :func:`get_credentials`
-      is used. This method is intended to be used when the environments is
+      is used. This method is intended to be used when the environment is
       known explicitly and detecting the environment implicitly would be
       superfluous.
 
@@ -302,7 +315,8 @@ def generate_signed_url(credentials, resource, expiration,
     :param resource: A pointer to a specific resource
                      (typically, ``/bucket-name/path/to/blob.txt``).
 
-    :type expiration: int, long, datetime.datetime, datetime.timedelta
+    :type expiration: :class:`int`, :class:`long`, :class:`datetime.datetime`,
+                      :class:`datetime.timedelta`
     :param expiration: When the signed URL should expire.
 
     :type api_access_endpoint: string

gcloud/credentials.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Custom exceptions for gcloud.storage package.
+"""Custom exceptions for :mod:`gcloud` package.
 
 See: https://cloud.google.com/storage/docs/json_api/v1/status-codes
 """
@@ -171,7 +171,7 @@ def make_exception(response, content, error_info=None, use_json=True):
     :param error_info: Optional string giving extra information about the
                        failed request.
 
-    :type use_json: boolean
+    :type use_json: bool
     :param use_json: Flag indicating if ``content`` is expected to be JSON.
 
     :rtype: instance of :class:`GCloudError`, or a concrete subclass.
@@ -213,7 +213,7 @@ def _walk_subclasses(klass):
 
 
 # Build the code->exception class mapping.
-for eklass in _walk_subclasses(GCloudError):
-    code = getattr(eklass, 'code', None)
+for _eklass in _walk_subclasses(GCloudError):
+    code = getattr(_eklass, 'code', None)
     if code is not None:
-        _HTTP_CODE_TO_EXCEPTION[code] = eklass
+        _HTTP_CODE_TO_EXCEPTION[code] = _eklass

gcloud/exceptions.py

@@ -104,7 +104,7 @@ def valid_filename(filename):
 def is_production_filename(filename):
     """Checks if the file contains production code.
 
-    :rtype: boolean
+    :rtype: bool
     :returns: Boolean indicating production status.
     """
     return not ('demo' in filename or 'test' in filename)
@@ -127,7 +127,7 @@ def get_files_for_linting(allow_limited=True):
     ``GCLOUD_REMOTE_FOR_LINT`` and ``GCLOUD_BRANCH_FOR_LINT`` can be set to
     specify a remote branch to diff against.
 
-    :type allow_limited: boolean
+    :type allow_limited: bool
     :param allow_limited: Boolean indicating if a reduced set of files can
                           be used.