Model Hello World examples like other languages. (#364)

Refactor Hello World example to look like other languages.  Avoid confusion by using .dox for
Doxygen documents.

Author: coryan

bigtable/CMakeLists.txt

@@ -132,7 +132,6 @@ else ()
         set(DOXYGEN_PROJECT_BRIEF "A C++ Client Library for Google Cloud Bigtable")
         set(DOXYGEN_PROJECT_NUMBER
                 "${BIGTABLE_CLIENT_VERSION_MAJOR}.${BIGTABLE_CLIENT_VERSION_MINOR}.${BIGTABLE_CLIENT_VERSION_PATCH}")
-        set(DOXYGEN_USE_MDFILE_AS_MAINPAGE ./doc/bigtable-main.md)
         set(DOXYGEN_EXAMPLE_PATH examples)
         set(DOXYGEN_PREDEFINED "BIGTABLE_CLIENT_NS=v${BIGTABLE_CLIENT_VERSION_MAJOR}")
         set(DOXYGEN_EXCLUDE_PATTERNS "*/client/internal/*;*/client/testing/*;*/*_test.cc")
@@ -160,7 +159,7 @@ add_subdirectory(tests)
 
 if (GOOGLE_CLOUD_CPP_ENABLE_CXX_EXCEPTIONS)
     add_subdirectory(benchmarks)
-    add_subdirectory(examples/quick_start)
+    add_subdirectory(examples)
 endif (GOOGLE_CLOUD_CPP_ENABLE_CXX_EXCEPTIONS)
 
 option(BIGTABLE_CLIENT_CLANG_TIDY

bigtable/doc/bigtable-hello-world.dox

@@ -0,0 +1,92 @@
+/*!
+@page bigtable-hello-world Example: C++ Hello World Application
+
+This example is a very simple "hello world" application, written in C++, that
+illustrates how to:
+
+- Connect to a Cloud Bigtable instance.
+- Create a new table.
+- Write data to the table.
+- Read the data back.
+- Delete the table.
+
+## Running the example
+
+This example uses the
+[Cloud Bigtable C++ Client Library](https://GoogleCloudPlatform.github.io/google-cloud-cpp)
+to communicate with Cloud Bigtable.
+
+To run the example program, follow the
+[instructions](https://github.com/GoogleCloudPlatform/google-cloud-cpp/tree/master/bigtable/examples/)
+for the example on GitHub.
+
+### Including the Necessary Headers
+
+The example uses the following headers:
+
+@snippet bigtable_hello_world.cc bigtable includes
+
+### Connecting to Cloud Bigtable to manage tables
+
+To manage tables, connect to Cloud Bigtable using
+`bigtable::CreateDefaultAdminClient()`:
+
+@snippet bigtable_hello_world.cc connect admin
+
+### Creating a table
+
+Create a table with `bigtable::TableAdmin::CreateTable()`:
+
+@snippet bigtable_hello_world.cc create table
+
+@see `bigtable::v0::TableAdmin` for additional operations to list, read, modify,
+and delete tables.
+
+### Connecting to Cloud Bigtable to manage data
+
+To manage data, connect to Cloud Bigtable using
+`bigtable::CreateDefaultDataClient()`:
+
+@snippet bigtable_hello_world.cc connect data
+
+### Writing Rows to a table
+
+Then write the data:
+
+@snippet bigtable_hello_world.cc write rows
+
+@see `bigtable::v0::Table::BulkApply()` to modify multiple rows in a single
+operation.  In addition to `SetCell()` there
+are functions to delete columns (e.g., `DeleteFromFamily()`) or to delete the
+whole row (`DeleteFromRow()`).
+
+### Reading a row by its key
+
+Get a row directly using its key with `bigtable::Table::ReadRow()`:
+
+@snippet bigtable_hello_world.cc read row
+
+@see `bigtable::v0::Filter` to filter the column families, columns, and even
+  the timestamps returned by `ReadRow()`.
+@see `bigtable::v0::Table::ReadRows()` to iterate over multiple rows.
+
+### Scanning all table rows
+
+Use `bigtable::Table::ReadRows()` to scan all of the rows in a table.
+
+@snippet bigtable_hello_world.cc scan all
+
+@see `bigtable::v0::RowRange` to scan only a portion of the table.
+
+### Deleting a table
+
+Delete a table with `TableAdmin::DeleteTable`.
+
+@snippet bigtable_hello_world.cc delete table
+
+## Putting it all together
+
+Here is the full example
+
+@snippet bigtable_hello_world.cc all code
+*/

bigtable/doc/bigtable-main.dox

@@ -0,0 +1,9 @@
+/*!
+@mainpage Cloud Bigtable C++ Client Library
+
+This page contains the reference guide to the Cloud Bigtable C++ Client Library.
+
+## Examples
+
+* @ref bigtable-hello-world "Hello World Example"
+*/

bigtable/doc/bigtable-main.md

@@ -16,11 +16,5 @@
 # to keep this particular file as simple as possible, as it is intended to be
 # part of the examples.
 
-add_executable(bigtable_create_table bigtable_create_table.cc)
-target_link_libraries(bigtable_create_table bigtable_client)
-
-add_executable(bigtable_write_row bigtable_write_row.cc)
-target_link_libraries(bigtable_write_row bigtable_client)
-
-add_executable(bigtable_read_row bigtable_read_row.cc)
-target_link_libraries(bigtable_read_row bigtable_client)
+add_executable(bigtable_hello_world bigtable_hello_world.cc)
+target_link_libraries(bigtable_hello_world bigtable_client)

…able/examples/quick_start/CMakeLists.txt bigtable/examples/CMakeLists.txtbigtable/examples/quick_start/CMakeLists.txt renamed to bigtable/examples/CMakeLists.txt bigtable/examples/quick_start/CMakeLists.txt renamed to bigtable/examples/CMakeLists.txt

@@ -0,0 +1,81 @@
+# Cloud Bigtable C++ Client Quick Start Code Samples
+
+This directory contains minimal examples to get started quickly, and are
+referenced from the Doxygen landing page as "Hello World".
+
+## Compiling the Examples
+
+These examples are compiled as part of the build for the Cloud Bigtable C++
+Client.  The instructions on how to compile the code are in the
+[top-level README](../../README.md) file.
+
+## Running the examples against the Cloud Bigtable Emulator
+
+The easiest way to run these examples is to use the Cloud Bigtable Emulator.
+This emulator is included as part of the
+[Google Cloud SDK](https://cloud.google.com/sdk/).
+
+### Installing the Emulator
+
+Follow the relevant
+[documentation](https://cloud.google.com/bigtable/docs/emulator) to install
+the emulator.
+
+### Running the Emulator
+
+Start the emulator as described in the documentation:
+
+```console
+$ gcloud beta emulators bigtable start
+```
+
+On a separate shell setup the necessary environment variables:
+
+```console
+$ $(gcloud beta emulators bigtable env-init)
+```
+
+## Running the examples against a production version of Cloud Bigtable
+
+You first need to create a production instance, the easiest way is to
+follow the
+[instructions](https://cloud.google.com/bigtable/docs/creating-instance)
+on the Cloud Bigtable site.
+
+### Configuring gRPC Root Certificates
+
+You may need to configure gRPC to accept the Google server certificates.
+gRPC expects to find a
+[PEM](https://en.wikipedia.org/wiki/Privacy-enhanced_Electronic_Mail) file
+with the list of trusted root certificates in `/usr/share/grpc/roots.pem`
+(or `${PREFIX}/share/grpc/roots.pem` if you installed gRPC with a different
+`PREFIX`, e.g. `/usr/local`).  If your system does not have this file installed
+you need to set the `GRPC_DEFAULT_SSL_ROOTS_FILE_PATH` to the location of this
+file.
+
+The gRPC source, included as a submodule of `google-cloud-cpp`, contains
+a version of this file. If you want to use that version use:
+
+```console
+$ GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=$HOME/google-cloud-cpp/third_party/grpc/etc/roots.pem
+$ export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH
+```
+
+### Authenticate with Google Cloud
+
+You may need to authenticate with Google Cloud Platform. The Google Cloud SDK
+offers a simple way to do so:
+
+```console
+$ gcloud auth login
+```
+
+## Running the Quick Start Examples using a Cloud Bigtable Instance
+
+After configuring gRPC, you can run the examples using:
+
+```console
+$ export PROJECT_ID=... # The name of your project
+$ export INSTANCE_ID=... # THe name of your instance
+$ ./bigtable_hello_world ${PROJECT_ID} ${INSTANCE_ID} example-table
+```