doc(pubsub): declutter landing pages (#10536)

google/cloud/pubsub/README.md

@@ -8,20 +8,6 @@ that process events.
 While this library is **GA**, please note that the Google Cloud C++ client libraries do **not** follow
 [Semantic Versioning](https://semver.org/).
 
-## Supported Platforms
-
-- Windows, macOS, Linux
-- C++14 (and higher) compilers (we test with GCC >= 7.3, Clang >= 6.0, and
-  MSVC >= 2017)
-- Environments with or without exceptions
-- Bazel (>= 4.0) and CMake (>= 3.5) builds
-
-## Documentation
-
-- Official documentation about the [Cloud Pub/Sub][cloud-pubsub-docs] service
-- [Reference doxygen documentation][doxygen-link] for each release of this client library
-- Detailed header comments in our [public `.h`][source-link] files
-
 ## Quickstart
 
 The [quickstart/](quickstart/README.md) directory contains a minimal environment
@@ -64,6 +50,8 @@ int main(int argc, char* argv[]) try {
 
 <!-- inject-quickstart-end -->
 
+## Build and Install
+
 - Packaging maintainers or developers who prefer to install the library in a
   fixed directory (such as `/usr/local` or `/opt`) should consult the
   [packaging guide](/doc/packaging.md).
@@ -75,27 +63,16 @@ int main(int argc, char* argv[]) try {
   project should consult the [quickstart guides](#quickstart) for the library
   or libraries they want to use.
 - Developers wanting to compile the library just to run some examples or
-  tests should read the current document.
+  tests should read the project's top-level
+  [README](/README.md#building-and-installing).
 - Contributors and developers to `google-cloud-cpp` should consult the guide to
   [set up a development workstation][howto-setup-dev-workstation].
 
-## Installation
+## More Information
 
-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
-
-See [`CONTRIBUTING.md`](/CONTRIBUTING.md) for details on how to
-contribute to this project, including how to build and test your changes
-as well as how to properly format your code.
-
-## Licensing
-
-Apache 2.0; see [`LICENSE`](/LICENSE) for details.
+- Official documentation about the [Cloud Pub/Sub][cloud-pubsub-docs] service
+- [Reference doxygen documentation][doxygen-link] for each release of this client library
+- Detailed header comments in our [public `.h`][source-link] files
 
 [cloud-pubsub-docs]: https://cloud.google.com/pubsub/docs/
 [doxygen-link]: https://googleapis.dev/cpp/google-cloud-pubsub/latest/

google/cloud/pubsub/doc/environment-variables.dox

@@ -0,0 +1,45 @@
+/*!
+
+@page pubsub-env Environment Variables
+
+A number of environment variables can be used to configure the behavior of
+the library.  There are also functions to configure this behavior in code. The
+environment variables are convenient when troubleshooting problems.
+
+@section pubsub-env-logging Logging
+
+`GOOGLE_CLOUD_CPP_ENABLE_TRACING=rpc`: turns on tracing for most gRPC
+calls. The library injects an additional Stub decorator that prints each gRPC
+request and response.  Unless you have configured you own logging backend,
+you should also set `GOOGLE_CLOUD_CPP_ENABLE_CLOG` to produce any output on
+the program's console.
+
+@see google::cloud::TracingComponentsOption
+
+`GOOGLE_CLOUD_CPP_TRACING_OPTIONS=...`: modifies the behavior of gRPC tracing,
+including whether messages will be output on multiple lines, or whether
+string/bytes fields will be truncated.
+
+@see google::cloud::TracingOptionsOption
+
+`GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes`: turns on logging in the library, basically
+the library always "logs" but the logging infrastructure has no backend to
+actually print anything until the application sets a backend or they set this
+environment variable.
+
+@see google::cloud::LogBackend
+@see google::cloud::LogSink
+
+@section pubsub-env-endpoint Endpoint Overrides
+
+`PUBSUB_EMULATOR_HOST=host:port`: tells the library to connect to the
+specified emulator rather than the default endpoint. Intended for testing only.
+
+@see google::cloud::EndpointOption
+
+@section pubsub-env-project Setting the Default Project
+
+`GOOGLE_CLOUD_PROJECT=...`: is used in examples and integration tests to
+configure the GCP project. This has no effect in the library.
+
+*/

google/cloud/pubsub/doc/error-handling.dox

@@ -0,0 +1,40 @@
+/**
+
+@page pubsub-error-handling Error Handling
+
+[StatusOr<T>]: @ref google::cloud::StatusOr
+
+This library never throws exceptions to signal error. In general, the library
+returns a [StatusOr<T>] if an error is possible. Some
+functions return objects that are not wrapped in a `StatusOr<>` but will
+themselves return a `StatusOr<>` to signal an error. For example, wrappers for
+asynchronous operations return `future<StatusOr<T>>`.
+
+Applications should check if the `StatusOr<T>` contains a value before using
+it, much like how you might check that a pointer is not null before
+dereferencing it. Indeed, a `StatusOr<T>` object can be used like a
+smart-pointer to `T`, with the main difference being that when it does not hold
+a `T` it will instead hold a `Status` object with extra information about the
+error.
+
+You can check that a `StatusOr<T>` contains a value by calling the `.ok()`
+method, or by using `operator bool()` (like with other smart pointers). If
+there is no value, you can access the contained `Status` object using the
+`.status()` member. If there is a value, you may access it by dereferencing
+with `operator*()` or `operator->()`. As with all smart pointers, callers must
+first check that the `StatusOr<T>` contains a value before dereferencing and
+accessing the contained value. Alternatively, callers may instead use the
+`.value()` member function which is defined to throw a `RuntimeStatusError` if
+there is no value.
+
+@note If you're compiling with exceptions disabled, calling `.value()` on a
+    `StatusOr<T>` that does not contain a value will terminate the program
+    instead of throwing.
+
+@par Example
+@snippet samples.cc example-status-or
+
+@see @ref google::cloud::future for more details on the type returned
+    by asynchronous operations.
+
+*/

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

@@ -5,110 +5,64 @@
 The Cloud Pub/Sub C++ Client library offers types and functions to use Cloud
 Pub/Sub from C++ applications.
 
-This library requires a C++14 compiler. It is supported (and tested) on multiple
-Linux distributions, macOS, and Windows.
+@tableofcontents{HTML:2}
 
 ## Quickstart
 
-The following instructions show you how to perform basic tasks in Cloud Pub/Sub
-using the C++ client library.
+The following "Hello World" program should give you a sense of how to use the
+library.
 
-### Before you begin
+@snippet quickstart.cc all
 
-1. Select or create a Google Cloud Platform (GCP) project using the
-   [manage resource page][resource-link]. Make a note of the project id as you
-   will need to use it later.
-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][gcloud-authorizing],
-   - or [login with your personal account][gcloud-authorizing]
+## Building and Installing
 
-@tableofcontents{HTML:2}
+- Packaging maintainers or developers who prefer to install the library in a
+  fixed directory (such as `/usr/local` or `/opt`) should consult the
+  [packaging guide].
+- Developers who prefer using a package manager such as
+  [vcpkg](https://vcpkg.io), [Conda](https://conda.io),
+  or [Conan](https://conan.io) should follow the instructions for their package
+  manager.
+- Developers wanting to use the libraries as part of a larger CMake or Bazel
+  project should consult the [quickstart guide].
+- Developers wanting to compile the library just to run some examples or
+  tests should read the project's top-level [README][project-build].
+- Contributors and developers to [google-cloud-cpp][github-link] should consult
+  the guide to [set up a development workstation][howto-setup-dev-workstation].
+
+## Next Steps
+
+- [Publisher::Publish()] - to efficiently publish Pub/Sub messages.
+- [BlockingPublisher::Publish()] - to publish a single Pub/Sub messages.
+- [Subscriber::Subscribe()] - to asynchronous receive Pub/Sub messages.
+- [Subscriber::Pull()] - to receive a single Pub/Sub messages.
+- @ref pubsub-error-handling to learn how the library reports run-time errors.
+- @ref pubsub-env-logging enabling logging. This can be an effective approach to
+  diagnose many problems.
+- @ref pubsub-env for environment variables affecting the library.
+- @ref pubsub-endpoint-example
+- @ref pubsub-auth-example
+- @ref publisher-mock shows how to write tests mocking [Publisher]
+- @ref subscriber-mock shows how to write tests mocking [Subscriber]
+
+[Publisher]: @ref google::cloud::pubsub::Publisher
+[Subscriber]: @ref google::cloud::pubsub::Subscriber
+[Publisher::Publish()]: @ref google::cloud::pubsub::Publisher::Publish()
+[BlockingPublisher::Publish()]: @ref google::cloud::pubsub::BlockingPublisher::Publish()
+[Subscriber::Subscribe()]: @ref google::cloud::pubsub::Subscriber::Subscribe()
+[Subscriber::Pull()]: @ref google::cloud::pubsub::Subscriber::Pull()
+
+[project-readme]:  https://github.com/googleapis/google-cloud-cpp#readme
+[project-build]:   https://github.com/googleapis/google-cloud-cpp#building-and-installing
+[howto-setup-dev-workstation]: https://github.com/googleapis/google-cloud-cpp/tree/main/doc/contributor/howto-guide-setup-development-workstation.md
+[github-readme]:    https://github.com/googleapis/google-cloud-cpp/tree/main/google/cloud/pubsub#readme
+[quickstart guide]: https://github.com/googleapis/google-cloud-cpp/tree/main/google/cloud/pubsub/quickstart#readme
+[packaging guide]:  https://github.com/googleapis/google-cloud-cpp/blob/main/doc/packaging%2Emd
+
+*/
 
-## Setting up your repo
-
-In order to use the Cloud Pub/Sub C++ client library from your own code, you'll
-need to configure your build system how to fetch and compile the Cloud C++
-client library. The Cloud Pub/Sub C++ client library natively supports the
-[Bazel](https://bazel.build/) and [CMake](https://cmake.org/) build systems.
-We've created a minimal, "Hello world", [quickstart repo][quickstart-link] that
-includes detailed instructions on how to compile the library for use in your
-application. You can fetch the source from [GitHub][github-link] as normal:
-
-@code{.sh}
-git clone https://github.com/googleapis/google-cloud-cpp.git
-cd google-cloud-cpp/google/cloud/pubsub/quickstart
-@endcode
-
-@par Example: Hello World
-@parblock
-The following shows the code that you'll run in the
-`google/cloud/pubsub/quickstart/` directory, which should give you a taste of
-the Cloud Pub/Sub C++ client library API.
-
-@include quickstart.cc
-@endparblock
-
-## Environment Variables
-
-There are several environment variables that can be set to configure certain
-behaviors in the library.
-
-- `GOOGLE_CLOUD_CPP_ENABLE_TRACING=rpc` turns on tracing for most gRPC
-  calls. The library injects an additional Stub decorator that prints each gRPC
-  request and response.  Unless you have configured you own logging backend,
-  you should also set `GOOGLE_CLOUD_CPP_ENABLE_CLOG` to produce any output on
-  the program's console.
-
-- `GOOGLE_CLOUD_CPP_TRACING_OPTIONS=...` modifies the behavior of gRPC tracing,
-  including whether messages will be output on multiple lines, or whether
-  string/bytes fields will be truncated.
-
-- `GOOGLE_CLOUD_PROJECT=...` is used in examples and integration tests to
-  configure the GCP project.
-
-- `PUBSUB_EMULATOR_HOST=host:port` tells the library to connect to the
-  specified emulator rather than the default endpoint.
-
-- `GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes` turns on logging in the library, basically
-  the library always "logs" but the logging infrastructure has no backend to
-  actually print anything until the application sets a backend or they set this
-  environment variable.
-
-## Error Handling
-
-This library never throws exceptions to signal error. In general, the library
-returns a [`StatusOr<T>`][status-or-header] if an error is possible. Some
-functions return objects that are not wrapped in a `StatusOr<>` but will
-themselves return a `StatusOr<T>` to signal an error. For example, wrappers for
-asynchronous operations return `future<StatusOr<T>>`.
-
-Applications should check if the `StatusOr<T>` contains a value before using
-it, much like how you might check that a pointer is not null before
-dereferencing it. Indeed, a `StatusOr<T>` object can be used like a
-smart-pointer to `T`, with the main difference being that when it does not hold
-a `T` it will instead hold a `Status` object with extra information about the
-error.
-
-You can check that a `StatusOr<T>` contains a value by calling the `.ok()`
-method, or by using `operator bool()` (like with other smart pointers). If
-there is no value, you can access the contained `Status` object using the
-`.status()` member. If there is a value, you may access it by dereferencing
-with `operator*()` or `operator->()`. As with all smart pointers, callers must
-first check that the `StatusOr<T>` contains a value before dereferencing and
-accessing the contained value. Alternatively, callers may instead use the
-`.value()` member function which is defined to throw a `RuntimeStatusError` if
-there is no value.
-
-@note If you're compiling with exceptions disabled, calling `.value()` on a
-    `StatusOr<T>` that does not contain a value will terminate the program
-    instead of throwing.
-
-@par Example
-@snippet samples.cc example-status-or
-
-## Override the default endpoint
+/**
+@page pubsub-endpoint-example Override the default endpoint
 
 In some cases, you may need to override the default endpoint used by the client
 library. Use the `google::cloud::EndpointOption` when initializing the client
@@ -124,8 +78,10 @@ Follow these links for additional examples
  [SubscriptionAdminClient](@ref SubscriptionAdminClient-endpoint-snippet)
  [SchemaAdminClient](@ref SchemaAdminClient-endpoint-snippet)
  [Publisher](@ref Publisher-endpoint-snippet)
+*/
 
-## Override the authentication configuration
+/**
+@page pubsub-auth-example Override the authentication configuration
 
 Some applications cannot use the default authentication mechanism (known as
 [Application Default Credentials]). You can override this default using
@@ -151,20 +107,6 @@ Follow these links for additional examples
 
 [Best practices for managing service account keys]: https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys
 [Application Default Credentials]: https://cloud.google.com/docs/authentication#adc
-
-## Next Steps
-
-- @ref publisher-mock
-- @ref subscriber-mock
-
-[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'
-[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/main/google/cloud/pubsub/quickstart
-[status-or-header]: https://github.com/googleapis/google-cloud-cpp/blob/main/google/cloud/status_or.h
-
 */
 
 /*! @page Publisher-endpoint-snippet Override @c Publisher Default Endpoint

google/cloud/pubsub/quickstart/quickstart.cc

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! [START pubsub_quickstart_publisher]
+//! [START pubsub_quickstart_publisher] [all]
 #include "google/cloud/pubsub/publisher.h"
 #include <iostream>
 
@@ -41,4 +41,4 @@ int main(int argc, char* argv[]) try {
   std::cerr << "google::cloud::Status thrown: " << status << "\n";
   return 1;
 }
-//! [END pubsub_quickstart_publisher]
+//! [END pubsub_quickstart_publisher] [all]