doc: improve instructions for WORKSPACE files (#1254)

We never explained that users need to load a Starlark function to use
`http_archive()`. Also fix the documentation to use the current release,
this will get "stale", but would be still functional and we warn users
to update the version and SHA256 in the comments.

Since I was fixing this I also updated the INSTALL.md file (and its
generator) with the changes from #1252.

Author: coryan

INSTALL.md

@@ -6,15 +6,15 @@
 There are two primary ways of obtaining `google-cloud-cpp-spanner`. You can use git:
 
 ```bash
-git clone [email protected]:googleapis/google-cloud-cpp-spanner.git $HOME/project
+git clone [email protected]:googleapis/google-cloud-cpp-spanner.git $HOME/google-cloud-cpp-spanner
 ```
 
 Or obtain the tarball release:
 
 ```bash
-mkdir -p $HOME/project
-wget -q https://github.com/googleapis/google-cloud-cpp-spanner/archive/v0.4.0.tar.gz
-tar -xf v0.4.0.tar.gz -C $HOME/project --strip=1
+mkdir -p $HOME/google-cloud-cpp-spanner
+wget -q https://github.com/googleapis/google-cloud-cpp-spanner/archive/v0.7.0.tar.gz
+tar -xf v0.7.0.tar.gz -C $HOME/google-cloud-cpp-spanner --strip=1
 ```
 
 # Installing google-cloud-cpp-spanner
@@ -84,12 +84,15 @@ download and compile `google-cloud-cpp-spanner` as part of you Bazel build. Add
 the following commands to your `WORKSPACE` file:
 
 ```Python
+# Add the necessary Starlark functions to fetch google-cloud-cpp-spanner.
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
 # Update the version and SHA256 digest as needed.
 http_archive(
     name = "com_github_googleapis_google_cloud_cpp_spanner",
-    sha256 = "1dbca07e3f268ffab4461a1d98b16201adda4688866a1929ac71c22c46e4fe74",
-    strip_prefix = "google-cloud-cpp-spanner-0.6.0",
-    url = "https://github.com/googleapis/google-cloud-cpp-spanner/archive/v0.6.0.tar.gz",
+    sha256 = "9d7bd3de8e38f7e4b3e917766ed08fd8c8ff59a8b2f0997c4b1cb781a6fd1558",
+    strip_prefix = "google-cloud-cpp-spanner-0.7.0",
+    url = "https://github.com/googleapis/google-cloud-cpp-spanner/archive/v0.7.0.tar.gz",
 )
 
 # Configure @com_google_googleapis to only compile C++ and gRPC:

ci/test-install/WORKSPACE

@@ -16,19 +16,22 @@
 # loaded into a different Bazel project.
 workspace(name = "com_github_googleapis_google_cloud_cpp_spanner_test_install")
 
-# Spanner currently does not have a release. Applications should use something
-# like the following:
+# To use the Cloud Spanner C++ client library applications should download it
+# using `http_archive()`. For example, use the following Starlark commands
+# (change the version and SHA256 hash as needed):
+#
+# load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 #
 # http_archive(
 #     name = "com_github_googleapis_google_cloud_cpp_spanner",
-#     url = "http://github.com/googleapis/google-cloud-cpp-spanner/archive/v0.1.0.tar.gz",
-#     strip_prefix = "google-cloud-cpp-spanner-0.1.0",
-#     sha256 = "...",
+#     sha256 = "9d7bd3de8e38f7e4b3e917766ed08fd8c8ff59a8b2f0997c4b1cb781a6fd1558",
+#     strip_prefix = "google-cloud-cpp-spanner-0.7.0",
+#     url = "https://github.com/googleapis/google-cloud-cpp-spanner/archive/v0.7.0.tar.gz",
 # )
 #
-
-# But we want to test that the *current* version is correct, the CI builds
-# always have the source in /v.
+# In this WORKSPACE file we want to test that the *current* version is correct,
+# the CI builds always have the source in /v, so we use:
+#
 local_repository(
     name = "com_github_googleapis_google_cloud_cpp_spanner",
     path = "/v",

ci/test-readme/generate-install.sh

@@ -26,15 +26,15 @@ cat <<'END_OF_PREAMBLE'
 There are two primary ways of obtaining `google-cloud-cpp-spanner`. You can use git:
 
 ```bash
-git clone [email protected]:googleapis/google-cloud-cpp-spanner.git $HOME/project
+git clone [email protected]:googleapis/google-cloud-cpp-spanner.git $HOME/google-cloud-cpp-spanner
 ```
 
 Or obtain the tarball release:
 
 ```bash
-mkdir -p $HOME/project
-wget -q https://github.com/googleapis/google-cloud-cpp-spanner/archive/v0.4.0.tar.gz
-tar -xf v0.4.0.tar.gz -C $HOME/project --strip=1
+mkdir -p $HOME/google-cloud-cpp-spanner
+wget -q https://github.com/googleapis/google-cloud-cpp-spanner/archive/v0.7.0.tar.gz
+tar -xf v0.7.0.tar.gz -C $HOME/google-cloud-cpp-spanner --strip=1
 ```
 
 # Installing google-cloud-cpp-spanner
@@ -104,12 +104,15 @@ download and compile `google-cloud-cpp-spanner` as part of you Bazel build. Add
 the following commands to your `WORKSPACE` file:
 
 ```Python
+# Add the necessary Starlark functions to fetch google-cloud-cpp-spanner.
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
 # Update the version and SHA256 digest as needed.
 http_archive(
     name = "com_github_googleapis_google_cloud_cpp_spanner",
-    sha256 = "1dbca07e3f268ffab4461a1d98b16201adda4688866a1929ac71c22c46e4fe74",
-    strip_prefix = "google-cloud-cpp-spanner-0.6.0",
-    url = "https://github.com/googleapis/google-cloud-cpp-spanner/archive/v0.6.0.tar.gz",
+    sha256 = "9d7bd3de8e38f7e4b3e917766ed08fd8c8ff59a8b2f0997c4b1cb781a6fd1558",
+    strip_prefix = "google-cloud-cpp-spanner-0.7.0",
+    url = "https://github.com/googleapis/google-cloud-cpp-spanner/archive/v0.7.0.tar.gz",
 )
 
 # Configure @com_google_googleapis to only compile C++ and gRPC:

google/cloud/spanner/doc/spanner-main.dox

@@ -107,12 +107,15 @@ In your [WORKSPACE][workspace-definition-link] file add a dependency to download
 and install the library, for example:
 
 @code {.py}
+# Add the necessary Starlark functions to fetch google-cloud-cpp-spanner.
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
 # Change the version and SHA256 hash as needed.
 http_archive(
     name = "com_github_googleapis_google_cloud_cpp_spanner",
-    sha256 = "1dbca07e3f268ffab4461a1d98b16201adda4688866a1929ac71c22c46e4fe74",
-    strip_prefix = "google-cloud-cpp-spanner-0.6.0",
-    url = "https://github.com/googleapis/google-cloud-cpp-spanner/archive/v0.6.0.tar.gz",
+    sha256 = "9d7bd3de8e38f7e4b3e917766ed08fd8c8ff59a8b2f0997c4b1cb781a6fd1558",
+    strip_prefix = "google-cloud-cpp-spanner-0.7.0",
+    url = "https://github.com/googleapis/google-cloud-cpp-spanner/archive/v0.7.0.tar.gz",
 )
 @endcode