Standardize readme files

Ajay Kannan · Ajay Kannan · commit 68408bf96f70 · 2015-10-12T10:56:34.000-07:00
diff --git a/README.md b/README.md
@@ -9,17 +9,12 @@ Java idiomatic client for [Google Cloud Platform][cloud-platform] services.
 
 -  [Homepage] (https://googlecloudplatform.github.io/gcloud-java/)
 -  [API Documentation] (http://googlecloudplatform.github.io/gcloud-java/apidocs)
--  [Examples] (http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/gcloud/examples/package-summary.html)
 
 This client supports the following Google Cloud Platform services:
 
 -  [Google Cloud Datastore] (#google-cloud-datastore)
 -  [Google Cloud Storage] (#google-cloud-storage)
 
-<!---
--  [Google Cloud Storage] (https://cloud.google.com/storage/)
---->
-
 > Note: This client is a work-in-progress, and may occasionally
 > make backwards-incompatible changes.
 
@@ -34,13 +29,23 @@ Add this to your pom.xml file
 </dependency>
 ```
 
-<!---
 Example Applications
 --------------------
 
--  `java-datastore-sample`_ - A sample using Cloud Datastore
-.. _java-datastore-sample: https://github.com/GoogleCloudPlatform/java-datastore-sample
---->
+- [`DatastoreExample`](https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/gcloud-java-examples/src/main/java/com/google/gcloud/examples/DatastoreExample.java) - A simple command line interface for the Cloud Datastore
+  - Read more about using this application on the [`gcloud-java-examples` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/gcloud/examples/DatastoreExample.html).
+- [`StorageExample`](https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/gcloud-java-examples/src/main/java/com/google/gcloud/examples/StorageExample.java) - A simple command line interface providing some of Cloud Storage's functionality
+  - Read more about using this application on the [`gcloud-java-examples` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/gcloud/examples/StorageExample.html).
+
+Authentication
+--------------
+
+There are multiple ways to authenticate to use Google Cloud services.
+
+1. When using `gcloud-java` libraries from within Compute/App Engine, no additional authentication steps are necessary.
+2. When using `gcloud-java` libraries elsewhere, there are two options:
+  * [Generate a JSON service account key](https://cloud.google.com/storage/docs/authentication?hl=en#service_accounts).  Supply a path to the downloaded JSON credentials file when building the options supplied to datastore/storage constructor.
+  * If running locally for development/testing, you can use use [Google Cloud SDK](https://cloud.google.com/sdk/?hl=en).  To use the SDK authentication, [download the SDK](https://cloud.google.com/sdk/?hl=en) if you haven't already.  Then login using the SDK (`gcloud auth login` in command line), and set your current project using `gcloud config set project PROJECT_ID`.
 
 Google Cloud Datastore
 ----------------------
@@ -57,6 +62,8 @@ Cloud Datastore for your project.
 See the ``gcloud-java`` API [datastore documentation][datastore-api] to learn how to interact
 with the Cloud Datastore using this Client Library.
 
+Here is a code snippet showing a simple usage example from within Compute/App Engine.  Note that you must [supply credentials](#authentication) if running this snippet elsewhere.
+
 ```java
 import com.google.gcloud.datastore.Datastore;
 import com.google.gcloud.datastore.DatastoreFactory;
@@ -101,6 +108,8 @@ Cloud Storage for your project.
 See the ``gcloud-java`` API [storage documentation][storage-api] to learn how to interact
 with the Cloud Storage using this Client Library.
 
+Here is a code snippet showing a simple usage example from within Compute/App Engine.  Note that you must [supply credentials](#authentication) if running this snippet elsewhere.
+
 ```java
 import static java.nio.charset.StandardCharsets.UTF_8;
 
@@ -127,27 +136,18 @@ if (!blob.exists()) {
 }
 ```
 
+Java Versions
+-------------
+
+Java 7 or above is required for using this client.
+
 Testing
 -------
 
 This library provides tools to help write tests for code that uses gcloud-java services.
 
 See [TESTING] to read more about using our testing helpers.
 
-Contributing
-------------
-
-Contributions to this library are always welcome and highly encouraged.
-
-See [CONTRIBUTING] for more information on how to get started.
-
-Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See [Code of Conduct][code-of-conduct] for more information.
-
-Java Versions
--------------
-
-Java 7 or above is required for using this client.
-
 Versioning
 ----------
 
@@ -157,6 +157,15 @@ 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.
 
+Contributing
+------------
+
+Contributions to this library are always welcome and highly encouraged.
+
+See [CONTRIBUTING] for more information on how to get started.
+
+Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See [Code of Conduct][code-of-conduct] for more information.
+
 License
 -------
 
diff --git a/gcloud-java-core/README.md b/gcloud-java-core/README.md
@@ -5,10 +5,10 @@ This module provides common functionality required by service-specific modules o
 
 [![Build Status](https://travis-ci.org/GoogleCloudPlatform/gcloud-java.svg?branch=master)](https://travis-ci.org/GoogleCloudPlatform/gcloud-java)
 [![Coverage Status](https://coveralls.io/repos/GoogleCloudPlatform/gcloud-java/badge.svg?branch=master)](https://coveralls.io/r/GoogleCloudPlatform/gcloud-java?branch=master)
+[![Maven](https://img.shields.io/maven-central/v/com.google.gcloud/gcloud-java-core.svg)](https://img.shields.io/maven-central/v/com.google.gcloud/gcloud-java-core.svg)
 
 -  [Homepage] (https://googlecloudplatform.github.io/gcloud-java/)
 -  [API Documentation] (http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/gcloud/package-summary.html)
--  [Examples] (http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/gcloud/examples/package-summary.html)
 
 Quickstart
 ----------
@@ -21,18 +21,18 @@ Add this to your pom.xml file
 </dependency>
 ```
 
+Java Versions
+-------------
+
+Java 7 or above is required for using this client.
+
 Contributing
 ------------
 
 Contributions to this library are always welcome and highly encouraged.
 
 See [CONTRIBUTING] for more information on how to get started.
 
-Java Versions
--------------
-
-Java 7 or above is required for using this client.
-
 Versioning
 ----------
 
diff --git a/gcloud-java-datastore/README.md b/gcloud-java-datastore/README.md
@@ -5,10 +5,10 @@ Java idiomatic client for [Google Cloud Datastore] (https://cloud.google.com/dat
 
 [![Build Status](https://travis-ci.org/GoogleCloudPlatform/gcloud-java.svg?branch=master)](https://travis-ci.org/GoogleCloudPlatform/gcloud-java)
 [![Coverage Status](https://coveralls.io/repos/GoogleCloudPlatform/gcloud-java/badge.svg?branch=master)](https://coveralls.io/r/GoogleCloudPlatform/gcloud-java?branch=master)
+[![Maven](https://img.shields.io/maven-central/v/com.google.gcloud/gcloud-java-datastore.svg)]( https://img.shields.io/maven-central/v/com.google.gcloud/gcloud-java-datastore.svg)
 
 -  [Homepage] (https://googlecloudplatform.github.io/gcloud-java/)
 -  [API Documentation] (http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/gcloud/datastore/package-summary.html)
--  [Examples] (http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/gcloud/examples/DatastoreExample.html)
 
 > Note: This client is a work-in-progress, and may occasionally
 > make backwards-incompatible changes.
@@ -24,6 +24,18 @@ Add this to your pom.xml file
 </dependency>
 ```
 
+Example Application
+--------------------
+[`DatastoreExample`](https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/gcloud-java-examples/src/main/java/com/google/gcloud/examples/DatastoreExample.java) is a simple command line interface for the Cloud Datastore.  Read more about using the application on the [`gcloud-java-examples` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/gcloud/examples/DatastoreExample.html).
+
+Authentication
+--------------
+
+See the [Authentication](https://github.com/GoogleCloudPlatform/gcloud-java#authentication) section in the main repository's README.
+
+About Google Cloud Datastore
+----------------------------
+
 Google [Cloud Datastore][cloud-datastore] is a fully managed, schemaless database for
 storing non-relational data. Cloud Datastore automatically scales with
 your users and supports ACID transactions, high availability of reads and
@@ -36,6 +48,8 @@ Cloud Datastore for your project.
 See the ``gcloud-java`` API [datastore documentation][datastore-api] to learn how to interact
 with the Cloud Datastore using this Client Library.
 
+Here is a code snippet showing a simple usage example from within Compute/App Engine.  Note that you must [supply credentials](https://github.com/GoogleCloudPlatform/gcloud-java#authentication) if running this snippet elsewhere.
+
 ```java
 import com.google.gcloud.datastore.Datastore;
 import com.google.gcloud.datastore.DatastoreFactory;
@@ -66,25 +80,18 @@ if (entity == null) {
 }
 ```
 
+Java Versions
+-------------
+
+Java 7 or above is required for using this client.
+
 Testing
 -------
 
 This library has tools to help write tests for code that uses the Datastore.
 
 See [TESTING] to read more about testing.
 
-Contributing
-------------
-
-Contributions to this library are always welcome and highly encouraged.
-
-See [CONTRIBUTING] for more information on how to get started.
-
-Java Versions
--------------
-
-Java 7 or above is required for using this client.
-
 Versioning
 ----------
 
@@ -94,6 +101,13 @@ 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.
 
+Contributing
+------------
+
+Contributions to this library are always welcome and highly encouraged.
+
+See [CONTRIBUTING] for more information on how to get started.
+
 License
 -------
 
diff --git a/gcloud-java-examples/README.md b/gcloud-java-examples/README.md
@@ -5,6 +5,7 @@ Examples for gcloud-java (Java idiomatic client for [Google Cloud Platform][clou
 
 [![Build Status](https://travis-ci.org/GoogleCloudPlatform/gcloud-java.svg?branch=master)](https://travis-ci.org/GoogleCloudPlatform/gcloud-java)
 [![Coverage Status](https://coveralls.io/repos/GoogleCloudPlatform/gcloud-java/badge.svg?branch=master)](https://coveralls.io/r/GoogleCloudPlatform/gcloud-java?branch=master)
+[![Maven](https://img.shields.io/maven-central/v/com.google.gcloud/gcloud-java-examples.svg)]( https://img.shields.io/maven-central/v/com.google.gcloud/gcloud-java-examples.svg)
 
 -  [Homepage] (https://googlecloudplatform.github.io/gcloud-java/)
 -  [Examples] (http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/gcloud/examples/package-summary.html)
@@ -49,13 +50,6 @@ To run examples from your command line:
   $mvn exec:java -Dexec.mainClass="com.google.gcloud.examples.StorageExample" -Dexec.args="delete <bucket_name> test.txt"
 ```
 
-Contributing
-------------
-
-Contributions to this library are always welcome and highly encouraged.
-
-See [CONTRIBUTING] for more information on how to get started.
-
 Java Versions
 -------------
 
@@ -70,6 +64,13 @@ 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.
 
+Contributing
+------------
+
+Contributions to this library are always welcome and highly encouraged.
+
+See [CONTRIBUTING] for more information on how to get started.
+
 License
 -------
 
diff --git a/gcloud-java-storage/README.md b/gcloud-java-storage/README.md
@@ -5,10 +5,10 @@ Java idiomatic client for [Google Cloud Storage] (https://cloud.google.com/stora
 
 [![Build Status](https://travis-ci.org/GoogleCloudPlatform/gcloud-java.svg?branch=master)](https://travis-ci.org/GoogleCloudPlatform/gcloud-java)
 [![Coverage Status](https://coveralls.io/repos/GoogleCloudPlatform/gcloud-java/badge.svg?branch=master)](https://coveralls.io/r/GoogleCloudPlatform/gcloud-java?branch=master)
+[![Maven](https://img.shields.io/maven-central/v/com.google.gcloud/gcloud-java-storage.svg)]( https://img.shields.io/maven-central/v/com.google.gcloud/gcloud-java-storage.svg)
 
 -  [Homepage] (https://googlecloudplatform.github.io/gcloud-java/)
 -  [API Documentation] (http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/gcloud/storage/package-summary.html)
--  [Examples] (http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/gcloud/examples/StorageExample.html)
 
 > Note: This client is a work-in-progress, and may occasionally
 > make backwards-incompatible changes.
@@ -24,8 +24,18 @@ Add this to your pom.xml file
 </dependency>
 ```
 
-Google Cloud Storage
-----------------------
+Example Application
+-------------------
+
+[`StorageExample`](https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/gcloud-java-examples/src/main/java/com/google/gcloud/examples/StorageExample.java) is a simple command line interface that provides some of Cloud Storage's functionality.  Read more about using the application on the [`gcloud-java-examples` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/gcloud/examples/StorageExample.html).
+
+Authentication
+--------------
+
+See the [Authentication](https://github.com/GoogleCloudPlatform/gcloud-java#authentication) section in the main repository's README.
+
+About Google Cloud Storage
+--------------------------
 
 [Google Cloud Storage][cloud-storage] is a durable and highly available
 object storage service. Google Cloud Storage is almost infinitely scalable
@@ -38,6 +48,8 @@ Cloud Storage for your project.
 See the ``gcloud-java`` API [storage documentation][storage-api] to learn how to interact
 with the Cloud Storage using this Client Library.
 
+Here is a code snippet showing a simple usage example from within Compute/App Engine.  Note that you must [supply credentials](https://github.com/GoogleCloudPlatform/gcloud-java#authentication) if running this snippet elsewhere.
+
 ```java
 import static java.nio.charset.StandardCharsets.UTF_8;
 
@@ -64,25 +76,18 @@ if (!blob.exists()) {
 }
 ```
 
+Java Versions
+-------------
+
+Java 7 or above is required for using this client.
+
 Testing
 -------
 
 This library has tools to help make tests for code using Cloud Storage.
 
 See [TESTING] to read more about testing.
 
-Contributing
-------------
-
-Contributions to this library are always welcome and highly encouraged.
-
-See [CONTRIBUTING] for more information on how to get started.
-
-Java Versions
--------------
-
-Java 7 or above is required for using this client.
-
 Versioning
 ----------
 
@@ -92,6 +97,13 @@ 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.
 
+Contributing
+------------
+
+Contributions to this library are always welcome and highly encouraged.
+
+See [CONTRIBUTING] for more information on how to get started.
+
 License
 -------
 
