Fixing some docstrings that did not render as intended

Sphinx successfully rendered some docstrings that did things different than intended. Found via visual inspection of a few of the rendered files (more to come). Also - using names of basic types (`dict` instead of `dictionary`, `bool` instead of `boolean`) since Sphinx recognizes them. - fixing some broken Sphinx links - fixing some broken URLs (404, docs moved) - adding formatting to unformatted text - renaming doc with underscores to use hyphen - removing an accidentally public var that was documented (eklass -> _eklass)

Author: dhermes

docs/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.
  """
 
@@ -305,12 +308,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 ``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
+ 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::
+ 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

@@ -46,7 +46,7 @@ class Key(object):
  :param path_args: May represent a partial (odd length) or full (even
  length) key path.
 
- :type kwargs: dictionary
+ :type kwargs: dict
  :param kwargs: Keyword arguments to be passed in.
 
  Accepted keyword arguments are

gcloud/datastore/key.py

@@ -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