doc(pubsub): more landing page improvements (googleapis#4978)

Some tweaks to the README file and the Doxygen landing pages.

ci/generate-markdown/generate-pubsub-readme.sh

@@ -34,6 +34,9 @@ that process events.
 Please note that the Google Cloud C++ client libraries do **not** follow
 [Semantic Versioning](http://semver.org/).
 
+> :warning: This library is under development and subject to breaking
+> changes without notice.
+
 ## Supported Platforms
 
 * Windows, macOS, Linux
@@ -72,6 +75,9 @@ cat <<'_EOF_'
 
 Please consult the [packaging guide](../../../doc/packaging.md) for detailed
 instructions to install the Google Cloud C++ client libraries.
+If your project uses [CMake](https://cmake.org) or [Bazel](https://bazel.build)
+check the [quickstart](quickstart/README.md) example for instructions to use
+this library in your project.
 
 ## Contributing changes
 

google/cloud/pubsub/README.md

@@ -10,6 +10,9 @@ that process events.
 Please note that the Google Cloud C++ client libraries do **not** follow
 [Semantic Versioning](http://semver.org/).
 
+> :warning: This library is under development and subject to breaking
+> changes without notice.
+
 ## Supported Platforms
 
 * Windows, macOS, Linux
@@ -73,6 +76,9 @@ int main(int argc, char* argv[]) try {
 
 Please consult the [packaging guide](../../../doc/packaging.md) for detailed
 instructions to install the Google Cloud C++ client libraries.
+If your project uses [CMake](https://cmake.org) or [Bazel](https://bazel.build)
+check the [quickstart](quickstart/README.md) example for instructions to use
+this library in your project.
 
 ## Contributing changes
 

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

@@ -21,8 +21,8 @@ using the C++ client library.
 2. Make sure that [billing is enabled][billing-link] for your project.
 3. Learn about [key terms and concepts][concepts-link] for Cloud Pub/Sub.
 4. Setup the authentication for the examples:
-   - [Configure a service account][authentication-quickstart],
-   - or [login with your personal account][gcloud-quickstart]
+   - [Configure a service account][gcloud-authorizing],
+   - or [login with your personal account][gcloud-authorizing]
 
 ### Setting up your repo
 
@@ -116,8 +116,7 @@ there is no value.
 [resource-link]: https://console.cloud.google.com/cloud-resource-manager 'Console Resource Manager'
 [billing-link]: https://cloud.google.com/billing/docs/how-to/modify-project 'How to: Modify Project'
 [concepts-link]: https://cloud.google.com/pubsub/docs/concepts 'Pub/Sub Concepts'
-[authentication-quickstart]: https://cloud.google.com/docs/authentication/getting-started 'Authentication Getting Started'
-[gcloud-quickstart]: https://cloud.google.com/sdk/docs/quickstarts
+[gcloud-authorizing]: https://cloud.google.com/sdk/docs/authorizing 'Authorizing Cloud SDK tools'
 [github-link]: https://github.com/googleapis/google-cloud-cpp 'GitHub Repository'
 [quickstart-link]:  https://github.com/googleapis/google-cloud-cpp/blob/master/google/cloud/pubsub/quickstart
 [status-or-header]: https://github.com/googleapis/google-cloud-cpp/blob/master/google/cloud/status_or.h

google/cloud/pubsub/quickstart/README.md

@@ -5,6 +5,14 @@ client library in your own project. These instructions assume that you have
 some experience as a C++ developer and that you have a working C++ toolchain
 (compiler, linker, etc.) installed on your platform.
 
+## Before you Begin
+
+To run the quickstart program you will need a working Google Cloud Platform
+(GCP) project, and an existing Cloud Pub/Sub Topic.
+The [Cloud Pub/Sub quickstarts][pubsub-quickstart-link] is a good place to find
+information on how to setup a GCP project and create a topic. Make a note of
+the project and topic ids as you will need them later.
+
 ## Configuring authentication for the C++ Client Library
 
 Like most Google Cloud Platform (GCP) services, Cloud Pub/Sub requires that
@@ -31,6 +39,9 @@ https://cloud.google.com/docs/authentication/production
 
 ## Using with Bazel
 
+> :warning: If you are using Windows or macOS there are additional instructions
+> at the end of this document.
+
 1. Install Bazel using [the instructions][bazel-install] from the `bazel.build`
    website.
 
@@ -41,22 +52,25 @@ https://cloud.google.com/docs/authentication/production
    bazel build ...
    ```
 
+   Note that, as it is often the case with C++ libraries, compiling these
+   dependencies may take several minutes.
+
 3. Run the example, change the place holder to appropriate values:
 
    ```bash
-   bazel run :quickstart -- [GCP PROJECT] [CLOUD SPANNER INSTANCE] [CLOUD SPANNER DATABASE]
+   bazel run :quickstart -- [GCP PROJECT ID] [TOPIC ID]
    ```
 
-If you are using Windows or macOS there are additional instructions at the end
-of this document.
-
 ## Using with CMake
 
+> :warning: If you are using Windows or macOS there are additional instructions
+> at the end of this document.
+
 1. Install CMake. The package managers for most Linux distributions include a
    package for CMake. Likewise, you can install CMake on Windows using a package
    manager such as [chocolatey][choco-cmake-link], and on macOS using
    [homebrew][homebrew-cmake-link]. You can also obtain the software directly
-   from the [cmake.org][https://cmake.org/download/].
+   from the [cmake.org](https://cmake.org/download/).
 
 2. Install the dependencies with your favorite tools. As an example, if you use
    [vcpkg](https://github.com/Microsoft/vcpkg.git):
@@ -66,6 +80,9 @@ of this document.
    ./vcpkg install google-cloud-cpp
    ```
 
+   Note that, as it is often the case with C++ libraries, compiling these
+   dependencies may take several minutes.
+
 3. Configure CMake, if necessary, configure the directory where you installed
    the dependencies:
 
@@ -78,11 +95,9 @@ of this document.
 4. Run the example, change the place holder to appropriate values:
 
    ```bash
-   .build/quickstart [GCP PROJECT] [CLOUD SPANNER INSTANCE] [CLOUD SPANNER DATABASE]
+   .build/quickstart [GCP PROJECT ID] [PUB/SUB TOPIC ID]
    ```
 
-If you are using Windows or macOS there are additional instructions at the end
-of this document.
 
 ## Platform Specific Notes
 
@@ -122,7 +137,7 @@ set GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=%cd%\roots.pem
 ```
 
 [bazel-install]: https://docs.bazel.build/versions/master/install.html
-[spanner-quickstart-link]: https://cloud.google.com/spanner/docs/quickstart-console
+[pubsub-quickstart-link]: https://cloud.google.com/pubsub/docs/quickstart-console
 [grpc-roots-pem-bug]: https://github.com/grpc/grpc/issues/16571
 [choco-cmake-link]: https://chocolatey.org/packages/cmake
 [homebrew-cmake-link]: https://formulae.brew.sh/formula/cmake