Merge pull request #673 from dhermes/standardize-readme

Updating README to meet unified gcloud-* format.

CONTRIBUTING.rst

@@ -309,6 +309,45 @@ we have customized (e.g. rewriting imports) for our library:
 - ``67b06019549a4db8168ff4c5171c9d701ac94a15``
 - ``f4a53ee64fad5f3d7f29a0341e6a72a060edfcc2``
 
+Supported Python Versions
+-------------------------
+
+We support:
+
+-  `Python 2.6`_
+-  `Python 2.7`_
+
+We plan to support:
+
+-  `Python 3.3`_
+-  `Python 3.4`_
+
+.. _Python 2.6: https://docs.python.org/2.6/
+.. _Python 2.7: https://docs.python.org/2.7/
+.. _Python 3.3: https://docs.python.org/3.3/
+.. _Python 3.4: https://docs.python.org/3.4/
+
+Supported versions can be found in our ``tox.ini`` `config`_.
+
+.. _config: https://github.com/GoogleCloudPlatform/gcloud-python/blob/master/tox.ini
+
+We explicitly decided not to support `Python 2.5`_ due to `decreased usage`_
+and lack of continuous integration `support`_.
+
+.. _Python 2.5: https://docs.python.org/2.5/
+.. _decreased usage: https://caremad.io/2013/10/a-look-at-pypi-downloads/
+.. _support: http://blog.travis-ci.com/2013-11-18-upcoming-build-environment-updates/
+
+We also explicitly decided to support Python 3 beginning with version
+3.3. Reasons for this include:
+
+-  Encouraging use of newest versions of Python 3
+-  Taking the lead of prominent open-source `projects`_
+-  `Unicode literal support`_ which allows for a cleaner codebase that
+   works in both Python 2 and Python 3
+
+.. _projects: http://flask.pocoo.org/docs/0.10/python3/
+.. _Unicode literal support: https://www.python.org/dev/peps/pep-0414/
 
 Contributor License Agreements
 ------------------------------

README.rst

@@ -1,46 +1,45 @@
 Google Cloud Python Client
 ==========================
 
-Python idiomatic client for Google Cloud Platform services.
+    Python idiomatic client for `Google Cloud Platform`_ services.
 
-|build| |coverage| |pypi|
--------------------------
+.. _Google Cloud Platform: https://cloud.google.com/
+
+|pypi| |build| |coverage|
 
 -  `Homepage`_
+-  `API Documentation`_
 
 .. _Homepage: https://googlecloudplatform.github.io/gcloud-python/
+.. _API Documentation: http://googlecloudplatform.github.io/gcloud-python/latest/
 
 This client supports the following Google Cloud Platform services:
 
 -  `Google Cloud Datastore`_
 -  `Google Cloud Storage`_
 
-.. _Google Cloud Datastore: https://cloud.google.com/products/cloud-datastore/
-.. _Google Cloud Storage: https://cloud.google.com/products/cloud-storage/
+.. _Google Cloud Datastore: https://cloud.google.com/datastore/
+.. _Google Cloud Storage: https://cloud.google.com/storage/
 
 If you need support for other Google APIs, check out the
 `Google APIs Python Client library`_.
 
 .. _Google APIs Python Client library: https://github.com/google/google-api-python-client
 
-Versioning
-----------
-
-This library follows `Semantic Versioning`_.
-
-.. _Semantic Versioning: http://semver.org/
-
-It is currently in major version zero (``0.y.z``), which means that anything
-may change at any time and the public API should not be considered
-stable.
-
 Quickstart
 ----------
 
 ::
 
     $ pip install gcloud
 
+Example Applications
+--------------------
+
+-  `gcloud-python-expenses-demo`_ - A sample expenses demo using Cloud Datastore and Cloud Storage
+
+.. _gcloud-python-expenses-demo: https://github.com/GoogleCloudPlatform/gcloud-python-expenses-demo
+
 Google Cloud Datastore
 ----------------------
 
@@ -50,25 +49,33 @@ your users and supports ACID transactions, high availability of reads and
 writes, strong consistency for reads and ancestor queries, and eventual
 consistency for all other queries.
 
-.. _Cloud Datastore: https://developers.google.com/datastore/
+.. _Cloud Datastore: https://cloud.google.com/datastore/docs
 
 See the `Google Cloud Datastore docs`_ for more details on how to activate
 Cloud Datastore for your project.
 
-.. _Google Cloud Datastore docs: https://developers.google.com/datastore/docs/activate
+.. _Google Cloud Datastore docs: https://cloud.google.com/datastore/docs/activate
 
 See the ``gcloud-python`` API `datastore documentation`_ to learn how to interact
 with the Cloud Datastore using this Client Library.
 
-.. _datastore documentation: https://googlecloudplatform.github.io/gcloud-python/datastore-api.html
+.. _datastore documentation: https://googlecloudplatform.github.io/gcloud-python/latest/datastore-api.html
 
 .. code:: python
 
     from gcloud import datastore
     datastore.set_defaults()
-    # Then do other things...
-    query = datastore.Query(kind='EntityKind')
+    # Create, populate and persist an entity
     entity = datastore.Entity(key=datastore.Key('EntityKind'))
+    entity.update({
+        'foo': u'bar',
+        'baz': 1337,
+        'qux': False,
+    })
+    # Then query for entities
+    query = datastore.Query(kind='EntityKind')
+    for result in query.fetch():
+        print result
 
 Google Cloud Storage
 --------------------
@@ -77,23 +84,23 @@ Google `Cloud Storage`_ allows you to store data on Google infrastructure with
 very high reliability, performance and availability, and can be used to
 distribute large data objects to users via direct download.
 
-.. _Cloud Storage: https://developers.google.com/storage/
+.. _Cloud Storage: https://cloud.google.com/storage/docs
 
 You need to create a Google Cloud Storage bucket to use this client
 library. Follow the steps on the `Google Cloud Storage docs`_
 to learn how to create a bucket.
 
-.. _Google Cloud Storage docs: https://developers.google.com/storage/docs/cloud-console#_creatingbuckets
+.. _Google Cloud Storage docs: https://cloud.google.com/storage/docs/cloud-console#_creatingbuckets
 
 See the ``gcloud-python`` API `storage documentation`_ to learn how to connect
 to Cloud Storage using this Client Library.
 
-.. _storage documentation: https://googlecloudplatform.github.io/gcloud-python/storage-api.html
+.. _storage documentation: https://googlecloudplatform.github.io/gcloud-python/latest/storage-api.html
 
 .. code:: python
 
-    import gcloud.storage
-    bucket = gcloud.storage.get_bucket('bucket-id-here', 'project-id')
+    from gcloud import storage
+    bucket = storage.get_bucket('bucket-id-here', 'project-id')
     # Then do other things...
     blob = bucket.get_blob('/remote/path/to/file.txt')
     print blob.download_as_string()
@@ -109,45 +116,29 @@ See `CONTRIBUTING`_ for more information on how to get started.
 
 .. _CONTRIBUTING: https://github.com/GoogleCloudPlatform/gcloud-python/blob/master/CONTRIBUTING.rst
 
-Supported Python Versions
+Python Versions
 -------------------------
 
-We support:
-
--  `Python 2.6`_
--  `Python 2.7`_
-
-We plan to support:
-
--  `Python 3.3`_
--  `Python 3.4`_
+We support `Python 2.6`_ and `Python 2.7`_ and plan to support `Python 3.3`_ and
+`Python 3.4`_. For more information, see `Supported Python Versions`_ in
+``CONTRIBUTING``.
 
 .. _Python 2.6: https://docs.python.org/2.6/
 .. _Python 2.7: https://docs.python.org/2.7/
 .. _Python 3.3: https://docs.python.org/3.3/
 .. _Python 3.4: https://docs.python.org/3.4/
+.. _Supported Python Versions: https://github.com/GoogleCloudPlatform/gcloud-python/blob/master/CONTRIBUTING.rst#supported-python-versions
 
-Supported versions can be found in our ``tox.ini`` `config`_.
-
-.. _config: https://github.com/GoogleCloudPlatform/gcloud-python/blob/master/tox.ini
-
-We explicitly decided not to support `Python 2.5`_ due to `decreased usage`_
-and lack of continuous integration `support`_.
-
-.. _Python 2.5: https://docs.python.org/2.5/
-.. _decreased usage: https://caremad.io/2013/10/a-look-at-pypi-downloads/
-.. _support: http://blog.travis-ci.com/2013-11-18-upcoming-build-environment-updates/
+Versioning
+----------
 
-We also explicitly decided to support Python 3 beginning with version
-3.3. Reasons for this include:
+This library follows `Semantic Versioning`_.
 
--  Encouraging use of newest versions of Python 3
--  Taking the lead of prominent open-source `projects`_
--  `Unicode literal support`_ which allows for a cleaner codebase that
-   works in both Python 2 and Python 3
+.. _Semantic Versioning: http://semver.org/
 
-.. _projects: http://flask.pocoo.org/docs/0.10/python3/
-.. _Unicode literal support: https://www.python.org/dev/peps/pep-0414/
+It is currently in major version zero (``0.y.z``), which means that anything
+may change at any time and the public API should not be considered
+stable.
 
 License
 -------